OBS Wiki - Benutzerbeiträge [de]

OBS/Kostenpflichtige Module/RESTServer/Server-Profile

2026-09-15T10:01:10Z

Rademacker:

{{Kostenpflichtige Module}}

=Server-Profile=

Ein '''Server''' im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.

Typische Einsatzfälle für mehrere Profile:

* Ein '''Public-Profil''' mit Standard-TLS auf Port 443 für externe Konsumenten.
* Ein '''Internal-mTLS-Profil''' auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
* Ein '''Debug-Profil''' mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server'''

==Felder des Server-Profils==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Nr || Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
|-
| Name || Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
|-
| Aktiv || Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
|-
| Info || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
|-
| Kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
|-
| mTLS || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
|-
| Cert || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
|-
| Key || PEM-Inhalt des privaten Schlüssels
|-
| Root-Cert || PEM-Inhalt des CA-Root-Zertifikats (Pflicht bei Standard-TLS, dort für Chain-Validierung, sowie bei mTLS, dort zusätzlich für Client-Cert-Verifikation)
|-
| Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
|-
| Limit Erfolg || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
|-
| Limit Fehler || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
|-
| Limit gesamt || Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
|-
| Max. Verbindungen || Obergrenze gleichzeitiger '''Verbindungen''' (<code>rsv_max_conn</code>). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server '''ohne HTTP-Antwort''' - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
|-
| Max. parallel || Obergrenze gleichzeitig '''verarbeiteter Anfragen''' (<code>rsv_max_parallel</code>). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server '''503''' mit <code>Retry-After</code>, der Client darf es also gleich erneut versuchen
|-
| Keine Kompression || Antworten dieses Profils werden '''nicht''' gepackt (<code>rsv_no_gzip</code>). Ohne Haken packt der Server JSON- und Textantworten ab 1024 Byte mit gzip, sofern der Client sie über <code>Accept-Encoding</code> annimmt. Der Haken betrifft nur die Antwortrichtung - komprimierte '''Anfragen''' nimmt der Server weiterhin entgegen
|}

Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.

==Modi==

{| class="wikitable"
! Modus !! Voraussetzungen !! Anwendung
|-
| '''Standard-TLS''' || Cert + Key + Root-Cert hinterlegt || Empfohlener Default für alle Server, die über das öffentliche Netz erreichbar sind
|-
| '''mTLS''' || Cert + Key + Root-Cert (CA) || Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
|-
| '''Plain-HTTP''' || Haken ''Kein SSL'' || Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt
|}

Beide Richtungen werden erkannt: Eine '''unverschlüsselte Anfrage an einen
TLS-Port''' (''http'' statt ''https'') beantwortet der Server mit '''HTTP 400'''
und einem Klartext-Hinweis. Die Abweisung erfolgt '''vor''' Authentifizierung,
Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also
keine Verarbeitung aus.

{{Hinweis|Bei Standard-TLS und mTLS fährt der Server ohne Cert/Key gar nicht erst hoch. Bei Standard-TLS ohne Root-Cert wird die Anlage abgelehnt - die Chain-Validierung benötigt das CA-Root. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.}}

==TLS-Version, Cipher und Zertifikats-Rotation==

* '''TLS-Version:''' Der Server erzwingt '''TLS 1.2'''. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
* '''Rotation:''' Ein Zertifikatswechsel erfolgt durch ändern der PEM-Inhalte in der DB und einen '''Neustart''' des REST-Dienstes (kein Hot-Reload). Bis zum Neustart läuft das alte Zertifikat weiter.
* '''Certificate-Pinning:''' Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher '''rechtzeitig ankündigen''' und mit einem '''Backup-Pin''' vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus.
==Rate-Limit je Profil==

Jedes Server-Profil führt '''eigene Zähler''' und kann '''eigene Schwellen''' haben.
Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit
aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.

Gezählt wird pro Schlüssel, und der Schlüssel ist der '''API-Key''' des Zugangs.
Sendet ein Konsument keinen API-Key (Zugang mit ''*''), wird ersatzweise auf die
'''IP-Adresse''' gezählt.

{{Hinweis|Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle
Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen
API-Key, teilen sich '''alle Benutzer einen Zähler'''. Mit den Standardwerten sind
das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen
Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst
höher setzen oder jedem Konsumenten einen eigenen API-Key geben.}}

Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden
'''beim Start''' des REST-Dienstes gelesen - eine Änderung wird erst nach einem
Neustart wirksam.

==Validierung beim Speichern==

Beim Speichern wird geprüft:

* Nr und Name müssen vergeben sein.
* Nr muss eindeutig sein.
* Name muss eindeutig sein.
* Bei nicht aktiviertem ''Kein SSL'' müssen Cert und Key vorhanden sein.
* Bei nicht aktiviertem ''mTLS'' (= Standard-TLS) muss Root-Cert vorhanden sein.

==Bindungen==

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.

===Aufruf===

In der Server-Liste den gewünschten Server markieren und '''F6''' drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.

===Felder===

{| class="wikitable"
! Feld !! Beschreibung
|-
| Host || IP-Adresse oder Hostname, auf dem gelauscht wird. ''0.0.0.0'' = alle IPv4-Adressen; ''127.0.0.1'' = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
|-
| Port || TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
|-
| Aktiv || Bindung wird beim Server-Start geladen
|-
| Standard|| Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt
|}

===Wirksamkeit===

Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.

==Listen-Funktionen==

In der Server-Liste:

* '''Einfg''' - neues Server-Profil
* '''Return''' - vorhandenes Profil bearbeiten
* '''F4''' - Sortierung wählen
* '''F6''' - Bindungs-Liste des markierten Servers

OBS/Kostenpflichtige Module/RESTServer/Datei-Upload

2026-09-15T10:00:58Z

Rademacker:

{{Kostenpflichtige Module}}

= Datei-Upload =

Ein Endpunkt nimmt Dateien nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]). Dann gilt nicht
das JSON-Body-Limit von 10 MB, sondern die pro Endpunkt konfigurierte Grösse
(<code>re_upload_size</code>, Standard 25 MB; Überschreitung -> '''413''').

Diese Seite beschreibt die '''Übertragung''' - was ein Client senden muss und was
der Server antwortet. Was das '''Skript''' davon sieht, sind vier Aufrufe
(<code>oReader.UploadPath()</code>, <code>UploadName()</code>,
<code>UploadType()</code>, <code>UploadSha()</code>) und steht unter
[[OBS/Kostenpflichtige Module/RESTServer/Scripting#Datei-Uploads|Scripting]].
Ein vollständiges Beispiel zeigt
[[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].

{{Hinweis|Der Server legt die Datei in einem temporären Verzeichnis ab und
'''verschiebt sie nicht selbst'''. Übernimmt das Skript sie nicht an ihren
Zielort, bleibt sie dort liegen.}}

== Einfacher Upload (multipart/form-data) ==

Eine Datei pro Request. Name und Content-Type stammen aus der
<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
Server speichert die erste Datei-Partie und ruft das Skript auf.

Die '''übrigen Partien''' des Formulars - alles ohne <code>filename=</code> -
liest das Skript über <code>oReader.Form('<name>')</code>. Der Wert ist UTF-8 und
auf 1024 Zeichen begrenzt, der Name auf Buchstaben, Ziffern und Unterstrich
reduziert. Zusatzangaben lassen sich damit im selben Request mitschicken, ohne sie
an die URL zu hängen:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cPfad : string;
cName : string;
cTyp : string;
cBemerk: string;
begin
cPfad := oReader.UploadPath();
cName := oReader.UploadName();
cTyp := oReader.UploadType();
cBemerk := oReader.Form('bemerkung'); // Formularfeld derselben Uebertragung

// ... Datei aus cPfad ins DMS / Zielverzeichnis uebernehmen ...

oWriter.Str('status' , 'ok');
oWriter.Str('dateiname', cName);
oWriter.Status(201);
end;
</syntaxhighlight>

== Resumable/Chunked Upload (Content-Range) ==

Für grosse Dateien überträgt der Client die Datei in Teilstücken (Chunks) mit dem
Header <code>Content-Range: bytes START-END/TOTAL</code>. Der Server hängt die
Chunks '''sequentiell''' an eine Session-Datei an und behandelt unvollständige
Uploads selbst - das Endpunkt-Skript läuft '''erst beim vollständigen Upload''',
und dann liefern ''oReader.UploadPath()'', ''UploadName()'' und ''UploadType()''
dasselbe wie beim einfachen Upload. Für die Teilstücke läuft es '''nicht'''.

Name und Content-Type sind im <code>Content-Range</code>-Protokoll nicht enthalten;
der Client liefert sie deshalb '''im ersten Chunk''' über den Header
<code>Upload-Metadata</code> (Format wie bei tus: kommagetrennte Paare
<code>schlüssel base64wert</code>, Werte Base64-kodiert):

<pre>
Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm
</pre>

Erkannt werden die Schlüssel <code>filename</code> (Pflicht) und
<code>filetype</code> (optional). Fehlt <code>filename</code> im ersten Chunk,
wird der Upload mit '''400''' abgelehnt, ohne dass eine Datei angelegt wird.
Folge-Chunks und Statusabfragen müssen die Metadaten nicht erneut senden.

Ablauf (vom Client gesteuert, der Server antwortet jeweils):

{| class="wikitable"
! Request !! Server-Antwort
|-
| Erster Chunk <code>Content-Range: bytes 0-1048575/5000000</code> + <code>Upload-Metadata</code> || '''308''' Resume Incomplete + Header <code>Upload-Id</code>, <code>Upload-Offset</code>, <code>Range</code>
|-
| weitere Chunks (jeweils <code>Upload-Id</code> mitsenden) || '''308''' mit aktualisiertem <code>Upload-Offset</code>
|-
| letzter Chunk (Bereich erreicht TOTAL) || normale Skript-Antwort (z.B. '''200'''/'''201''')
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> || aktueller <code>Upload-Offset</code>, ohne anzuhängen (Resume)
|}

{| class="wikitable"
! Header !! Richtung !! Bedeutung
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
|-
| Upload-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
|-
| Upload-Id || Request/Response || Session-Kennung. Fehlt sie im ersten Request, erzeugt der Server eine und gibt sie zurück; alle Folge-Chunks müssen sie mitsenden.
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
|}

Der Server hängt einen Chunk '''nur an, wenn START dem bereits gespeicherten Stand
entspricht'''. Bei Abweichung (doppelter Chunk, Lücke) wird nicht angehängt,
sondern der aktuelle ''Upload-Offset'' zurückgemeldet - der Client setzt ab dort
neu auf. Eine separate Statusabfrage ist für ein Resume daher nicht zwingend nötig.

Überschreitet ein Chunk bzw. die Gesamtgrösse das Limit (''re_upload_size''),
antwortet der Server mit '''413 Payload Too Large'''.

{{Hinweis|Der Upload-Status liegt prozesslokal im Speicher. Nach einem Neustart des Servers muss ein unvollständiger Upload neu begonnen werden.}}

== Komprimierte Uploads ==

Ein Upload-Körper mit dem Header <code>Content-Encoding</code> wird mit '''415 Unsupported Media Type''' abgewiesen - bei beiden Verfahren, einfach wie chunked.

Der Grund ist nicht Bequemlichkeit. Bei einem chunked Upload bliebe offen, ob <code>Content-Range</code> die gepackten oder die rohen Bytes zählt, und die SHA256-Prüfsumme bezöge sich nach einem Entpacken auf eine andere Datei, als der Client gesendet hat. Etablierte Protokolle - tus, S3 Multipart, Google Resumable Upload, Azure Blob - behandeln Kompression aus demselben Grund als Eigenschaft der '''gespeicherten Datei''' und nicht der Übertragung.

Wer gepackt hochladen will, packt die Datei '''selbst''' und lädt sie als <code>export.csv.gz</code> hoch. Offsets, Prüfsumme und Wiederaufnahme stimmen dann, und das Endpunkt-Skript bekommt Name und Typ wie gewohnt über <code>_OBS_UPLOAD_NAME</code> und <code>_OBS_UPLOAD_CONTENTTYPE</code>.

OBS/Kostenpflichtige Module/RESTServer/Datei-Download

2026-09-15T10:00:47Z

Rademacker:

{{Kostenpflichtige Module}}

= Datei-Download =

Ein Endpunkt kann statt eines JSON-Körpers eine '''Datei''' ausliefern - PDF, CSV,
Bilder, eine APK. Das Skript entscheidet das mit einem einzigen Aufruf, alles
Weitere macht der Server: Content-Type, Dateiname, Bereichsanfragen und, bei
temporären Dateien, das Aufräumen.

Anders als beim [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
braucht es dafür '''keine Freischaltung''' am Endpunkt. Ein Download entsteht
dadurch, dass das Skript ihn erzeugt, nicht dadurch, dass ein Client ihn anfragt.

== Die zwei Aufrufe ==

{| class="wikitable"
! Aufruf !! Für !! Nach dem Senden !! Wiederaufsetzbar
|-
| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> || Dateien, die es schon gibt und weiter geben wird || bleibt liegen || '''ja''' (206/Range)
|-
| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> || Ergebnisse, die je Abruf entstehen || wird '''gelöscht''' || nein
|}

<syntaxhighlight lang="pascal" line>
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cPfad: string;
cName: string;
begin
cUid := oReader.Path('uid');

if (not BelegGehoertZuMandant(oReader.Claim('tenant'), cUid)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Beleg nicht gefunden');
exit;
end;

cPfad := BelegPfad(cUid);
cName := 'Rechnung_' + cUid + '.pdf';

oWriter.SendFile(cPfad, cName, 'application/pdf');
end;
</syntaxhighlight>

{{Hinweis|'''Datei oder Felder - nicht beides.''' Schreibt ein Skript Felder
'''und''' ruft <code>SendFile</code>, ist das ein Strukturfehler wie eine
unbalancierte Verschachtelung: der Server antwortet '''500''' und nennt die Stelle
im Protokoll. <code>Error()</code> nach <code>SendFile</code> verwirft die Datei
und liefert die Fehlerhülle - die Ablehnung gewinnt.}}

== Was der Server dazu tut ==

{| class="wikitable"
! Kopfzeile !! Wert
|-
| Content-Type || der übergebene Typ; ohne Angabe <code>application/octet-stream</code>
|-
| Content-Disposition || <code>attachment</code> mit dem übergebenen Namen, nach RFC 5987 kodiert
|-
| Content-Length || Länge der Datei bzw. des angeforderten Bereichs
|-
| Accept-Ranges || <code>bytes</code> bei <code>SendFile</code>, <code>none</code> bei <code>SendTempFile</code>
|-
| ETag, Last-Modified || nur bei <code>SendFile</code>, aus Grösse und Änderungszeitpunkt
|}

'''Umlaute im Dateinamen''' sind unbedenklich. Header-Werte müssen ASCII sein,
deshalb schreibt der Server zwei Angaben: <code>filename=</code> mit einem
ausgeschriebenen Rückfallnamen (''Rechnung_Müller.pdf'' wird zu
''Rechnung_Mueller.pdf'') und <code>filename*=</code> mit dem echten Namen
UTF-8-kodiert. Jeder heutige Browser nimmt den zweiten.

Der Pfad wird '''nicht geprüft'''. Ein Skript kann über <code>Base.GFile</code>
ohnehin jede Datei des Servers lesen; eine Schranke nur an dieser Stelle würde
Sicherheit vortäuschen, die es nicht gibt.

{{Hinweis|'''Den Pfad niemals ungeprüft aus einem Client-Wert bilden.''' Ein
Endpunkt <code>/public/{name}</code>, der <code>{name}</code> an ein
Basisverzeichnis hängt, liefert bei <code>..%2F..%2Fobs.ini</code> die
Konfiguration aus. Entweder eine feste Zuordnung im Skript (''apk'' -> fester
Pfad), oder eine Tabelle mit freigegebenen Dateien - nie den Rohwert.}}

== Wiederaufnahme abgebrochener Downloads ==

Bei <code>SendFile</code> wertet der Server den Kopf <code>Range</code> aus.
Unterstützt wird '''ein''' Bereich je Anfrage, in den drei Formen, die Clients
tatsächlich senden:

{| class="wikitable"
! Range !! Bedeutung
|-
| <code>bytes=0-1023</code> || fester Bereich
|-
| <code>bytes=500-</code> || ab Offset bis zum Ende
|-
| <code>bytes=-500</code> || die letzten 500 Bytes
|}

Der Server antwortet dann mit '''206 Partial Content''' und
<code>Content-Range: bytes <von>-<bis>/<gesamt></code>.

{| class="wikitable"
! Fall !! Antwort
|-
| Kein <code>Range</code>-Kopf || '''200''' mit der ganzen Datei
|-
| Mehrere Bereiche (Komma) || '''200''' mit der ganzen Datei - die Spezifikation erlaubt das ausdrücklich
|-
| Bereich hinter dem Dateiende || '''416 Range Not Satisfiable''' mit <code>Content-Range: bytes */<gesamt></code>
|-
| <code>If-Range</code> stimmt nicht mehr || '''200''' mit der ganzen Datei
|}

'''Warum <code>If-Range</code> zählt:''' Setzt ein Client einen Download fort und
die Datei hat sich zwischenzeitlich geändert, entstünde aus zwei Ständen eine
Datei, die erst beim Öffnen auffällt. Schickt der Client seinen ETag in
<code>If-Range</code> mit und passt der nicht mehr, liefert der Server lieber alles
neu.

{{Hinweis|'''SendTempFile kann nicht fortgesetzt werden''', und das ist keine
Lücke: Die Datei ist nach dem Senden gelöscht, ein zweiter Abruf fände sie nicht
mehr vor - und eine Neuerzeugung lieferte andere Bytes, sobald sich die Daten
geändert haben. Der Server meldet deshalb <code>Accept-Ranges: none</code>, damit
ein Client es gar nicht erst versucht.}}

== Öffentliche Dateien ohne API-Key ==

Für Artefakte, die für jeden bestimmt sind - eine Test-APK, ein Handbuch - kann
der Endpunkt ohne <code>apikey</code>-Header erreichbar sein. Dafür genügt
Konfiguration, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]]:

# Zugang mit <code>ra_apikey = *</code>, <code>ra_jwt = 0</code>, <code>ra_cors_origin</code> '''leer'''
# In <code>RESTSRV_ACCESS</code> '''nur''' diesen einen Endpunkt freigeben

Die zweite Zeile ist die eigentliche Grenze: Für jeden anderen Endpunkt antwortet
der Server '''403''', auch wenn der Zugang existiert.

{{Hinweis|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt der
Endpunkt weder Mandant noch Rolle - es gibt nichts, woran er eine Berechtigung
festmachen könnte ausser dem, was in der URL steht. Kundenbelege gehören deshalb
über den authentifizierten Weg, nicht hierher.}}

Für eine Android-APK kommt hinzu: Content-Type
<code>application/vnd.android.package-archive</code>, am Gerät muss "Unbekannte
Apps installieren" für den Browser freigegeben sein, und die Signatur sollte über
alle Testversionen konstant bleiben - sonst gibt es beim späteren Wechsel in den
Play Store auf jedem Testgerät einen Installationskonflikt.

== Grenzen ==

{| class="wikitable"
! Was !! Stand
|-
| HEAD || wird '''nicht''' unterstützt (''405''). Browser brauchen es nicht; relevant nur für <code>wget --continue</code>, <code>curl -C -</code> und Download-Manager, die meist auf GET zurückfallen.
|-
| Mehrere Bereiche je Anfrage || nicht unterstützt (ganze Datei mit 200)
|-
| Liegengebliebene Temp-Dateien || Bricht der Server mitten im Senden ab, bleibt eine <code>SendTempFile</code>-Datei stehen. Das temporäre Verzeichnis wird von aussen geleert.
|-
| Idempotenz || Eine Dateiantwort wird '''nicht''' im Idempotenz-Store festgeschrieben - sie liesse sich nicht wiedergeben. Der <code>Idempotency-Key</code> bleibt danach benutzbar.
|-
| Kompression || Dateiantworten werden '''nicht''' gepackt, auch wenn der Client <code>Accept-Encoding: gzip</code> sendet. Sie sind meist bereits komprimiert (PDF, Bild, ZIP), und ein gepackter Auslauf hätte keine feste Länge mehr - <code>Content-Length</code>, <code>ETag</code>, <code>Accept-Ranges</code> und die Wiederaufnahme hängen daran. Wer einen grossen CSV- oder XML-Export gepackt ausliefern will, packt ihn im Skript und liefert ihn als <code>.gz</code> aus.
|}

OBS/Kostenpflichtige Module/RESTServer/Endpunkte

2026-09-15T10:00:38Z

Rademacker:

{{Kostenpflichtige Module}}

= Endpunkte =

Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
realisiert und ist genau einem Server-Profil zugeordnet.

== Routing über Pfad-Templates ==

Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
'''Platzhalter''' enthalten:

* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
* '''Platzhalter''' in geschweiften Klammern – z. B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.

Beispiele für gültige Templates:

{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}

=== Präzedenz bei mehreren Treffern ===

Passen mehrere Templates auf denselben Pfad, '''gewinnt das spezifischste''' –
also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code>
das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf
<code>/orders/{uid}</code> matcht.

== Hauptfelder eines Endpunkts ==

{| class="wikitable"
! Feld !! Spalte !! Zweck
|-
| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code>
|-
| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
|-
| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
|-
| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
|-
| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
|-
| '''Info''' || – || Dokumentations-Freitext
|-
| '''Datei-Upload''' || <code>re_upload</code> || Erlaubt Datei-Uploads an diesem Endpunkt (<code>0</code> = aus, <code>1</code> = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
|-
| '''Max. Upload-Grösse''' || <code>re_upload_size</code> || Maximale Dateigrösse in MB. Leer/0 = Standard 25 MB. Überschreitung wird mit 413 abgelehnt.
|}

== Pfad-Parameter im Skript ==

Die aus den Platzhaltern erfassten Werte liest das Endpunkt-Skript über
<code>oReader.Path</code>:

<syntaxhighlight lang="pascal">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
cUid := oReader.Path('uid'); // aus /orders/{uid}
// ...
end;
</syntaxhighlight>

Diese Werte stammen aus dem Routing und können nicht durch den Client
überschrieben werden.

== Datei-Uploads ==

Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.

Die maximal zulässige Dateigrösse wird pro Endpunkt über <code>re_upload_size</code>
(in MB) festgelegt; ohne Angabe gilt der Standard von '''25 MB'''. Wird das
Limit überschritten, antwortet der Server mit '''413 Payload Too Large'''. Für
Uploads gilt nicht das JSON-Body-Limit (10 MB), sondern dieses Endpunkt-Limit.
Der Originalname (beim resumable Upload über den Header <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit 413/400 abgelehnt. Das Skript liest Pfad, Name, Content-Type und die SHA-256-Prüfsumme der gespeicherten Datei über <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code> und <code>UploadSha()</code>; bei <code>multipart/form-data</code> die übrigen Formularfelder über <code>oReader.Form('<name>')</code>.

'''Das Übertragungsprotokoll''' - Header, Statuscodes, Resume-Verhalten - steht auf einer eigenen Seite: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].

Unterstützt werden zwei Übertragungsarten:

* '''Einfacher Upload''' per <code>multipart/form-data</code> (eine Datei pro Request).
* '''Resumable/Chunked Upload''' per <code>Content-Range</code> (grosse Dateien, fortsetzbar nach Abbruch).

Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und
übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage,
DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und
Beispiele: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Datei-Downloads ==

Ein Endpunkt kann eine '''Datei''' statt eines JSON-Körpers zurückgeben -
PDF, CSV, eine APK. Dafür ist '''keine Freischaltung''' nötig: ein Download
entsteht dadurch, dass das Skript ihn mit <code>oWriter.SendFile(...)</code>
bzw. <code>oWriter.SendTempFile(...)</code> erzeugt, nicht dadurch, dass ein
Client ihn anfragt.

Content-Type, Dateiname, Bereichsanfragen (<code>Range</code>, '''206'''),
ETag und das Aufräumen temporärer Dateien übernimmt der Server. Einzelheiten:
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].

== HTTP-Methode ==

Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
Pfad-Formen (z. B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
'''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.

== URL-Struktur ==

<pre>
http://[Host][:Port][Pfad-Template]
</pre>

Beispiele:
* <code>https://api.meinserver.de/orders</code>
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>

== Versionierung ==

Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z. B. <code>/orders/v1</code> oder
<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:

# Bestehenden Endpunkt unverändert lassen.
# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
# Berechtigungen für neue Konsumenten setzen.
# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.

== Zugriffskontrolle ==

Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
dürfen.

{{Achtung|'''Ein Endpunkt besteht aus zwei Zeilen, und beide werden von Hand
gepflegt:''' der Eintrag in <code>RESTSRV_ENDPOINTS</code> und die Berechtigung
in <code>RESTSRV_ACCESS</code>. Fehlt die zweite, antwortet der Endpunkt
'''403''' - und sieht dabei fertig aus: Pfad, Skript und Server-Profil stehen
korrekt da, der Aufruf kommt trotzdem nicht durch. Das ist die häufigste Ursache
für ein „der Endpunkt ist doch angelegt" und kostet jedes Mal eine
Fehlersuche, weil der Statuscode nach einem Rechteproblem des Konsumenten
aussieht und nicht nach einer fehlenden Konfigurationszeile.

Beim Anlegen also '''immer beide Zeilen''', und beim Prüfen eines
<code>403</code> zuerst nachsehen, ob die zweite existiert.}} Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
Zugriff '''pro Pfad-Form''' granular vergeben (z. B. Lesen von
<code>/orders/{uid}</code> erlauben, aber das ändernde
<code>PUT /orders/{uid}/modules/{code}</code> nicht).

== Caching ==

Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
(TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher
erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
zwingend sofort.

== HTTP-Fehlercodes ==

{| class="wikitable"
! Code !! Ursache
|-
| '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
|-
| '''403''' || Zugang fehlt in der Berechtigungsliste
|-
| '''401''' || API-Key ungültig/fehlend, JWT abgelaufen oder Sitzung gesperrt (''AUTH_EXPIRED'')
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
|-
| '''405''' || Das Endpunkt-Skript hat für die angefragte HTTP-Methode keine Funktion; der Header <code>Allow</code> nennt die vorhandenen
|-
| '''206''' || Teilantwort eines Datei-Downloads auf eine <code>Range</code>-Anfrage; die Antwort enthält <code>Content-Range</code>
|-
| '''416''' || Der angefragte <code>Range</code> liegt hinter dem Dateiende; die Antwort nennt in <code>Content-Range</code> die wirkliche Grösse
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>); oder ein <code>Content-Encoding</code>, das der Server nicht entpacken kann - unterstützt wird allein <code>gzip</code> (siehe [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Kompression)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>); oder der Anfragekörper überschreitet 10 MB bzw. - gepackt gesendet - das 400fache der gesendeten Grösse
|-
| '''429''' || Rate-Limit überschritten; die Antwort enthält den Header <code>Retry-After</code>
|-
| '''503''' || Eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet; die Antwort enthält <code>Retry-After</code>
|-
| '''409''' || Ein früherer Aufruf mit demselben <code>Idempotency-Key</code> ist ohne Ergebnis geblieben (<code>IDEMPOTENCY_UNRESOLVED</code>)
|-
| '''422''' || Derselbe <code>Idempotency-Key</code> wurde mit '''anderem''' Inhalt gesendet (<code>IDEMPOTENCY_KEY_REUSED</code>)
|-
| '''400''' || Die Anfrage wurde unverschlüsselt an einen TLS-Port geschickt (<code>http</code> statt <code>https</code>). Die Abweisung erfolgt vor Authentifizierung und Endpunkt-Skript
|}

Jede Fehlerantwort besteht aus einem <code>error</code>-Objekt mit
maschinenlesbarem Code - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. <code>201</code>, <code>204</code>, <code>409</code>, <code>422</code>) sowie Response-Header wie <code>ETag</code> oder <code>Location</code> - siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Idempotenz ==

Schickt ein Konsument bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code>
oder <code>DELETE</code> den Header <code>Idempotency-Key</code>, sorgt der Server
selbst dafür, dass eine wiederholte Sendung '''keine Zweitwirkung''' hat. Das gilt
für '''jeden''' Endpunkt - es muss weder am Endpunkt etwas eingestellt noch im
Skript etwas programmiert werden.

{| class="wikitable"
! Situation !! Antwort des Servers
|-
| Erster Aufruf || Endpunkt läuft normal, das Ergebnis wird zum Schlüssel gespeichert
|-
| Wiederholung, gleicher Inhalt || '''Gespeicherte Antwort''' (gleicher Statuscode, gleicher Body, gleiche Header) plus Header <code>Idempotent-Replay: true</code>. Das Skript läuft '''nicht'''
|-
| Wiederholung, anderer Inhalt || '''422''' <code>IDEMPOTENCY_KEY_REUSED</code> - derselbe Schlüssel für einen anderen Inhalt ist ein Client-Fehler
|-
| Erster Aufruf läuft noch || '''503''' <code>IDEMPOTENCY_IN_PROGRESS</code> mit <code>Retry-After</code>. Beim nächsten Versuch liegt die gespeicherte Antwort vor
|-
| Früherer Aufruf ohne Ergebnis || '''409''' <code>IDEMPOTENCY_UNRESOLVED</code>. Nur noch nach einem '''harten Abbruch''' des Dienstes zwischen Verarbeitung und Festschreiben; ob die Buchung stattgefunden hat, ist unbekannt. Der Aufräumlauf gibt solche Einträge nach 24 Stunden frei und protokolliert sie
|}

Wichtig für die Auslegung eines Endpunkts:

* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* Antwortet das Skript mit '''4xx''' (fachliche Ablehnung), wird der Schlüssel wieder '''freigegeben''' - der Konsument darf ihn nach Korrektur erneut verwenden. Sonst würde ein einziger Validierungsfehler den Schlüssel dauerhaft blockieren.
* Endet die Verarbeitung mit '''5xx''' oder einem Skript-Fehler, wird der Schlüssel '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden.
* Das ist eine bewusste Abwägung (geändert 2026-08-25): Bleibt der Schlüssel nach einem Serverfehler belegt, ist der Vorgang '''unwiederholbar''' - der Client bekommt dauerhaft 503 und müsste die erfasste Arbeit verwerfen. Garantierter Datenverlust wiegt schwerer als ein möglicher Doppelsatz.
* '''Folge für die Auslegung:''' ein schreibender Endpunkt sollte selbst wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.

Der Schlüssel gilt je '''Zugang, Methode und Pfad'''. Derselbe
<code>Idempotency-Key</code> an einem anderen Endpunkt ist damit ein eigener
Vorgang - der Konsument muss ihn nicht global eindeutig vergeben, aber pro Vorgang
'''stabil wiederverwenden''' (also nicht bei jedem Wiederholversuch neu erzeugen).

Die Einträge stehen in <code>RESTSRV_IDEMPOTENCY</code> und werden nach 30 Tagen
automatisch aufgeräumt. Einträge ohne Ergebnis werden '''nicht''' automatisch
gelöscht, sondern im Protokoll gemeldet.

== WebHooks ==

WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
gespeichert und der Endpunkt anschließend automatisch gelöscht.

Typischer Einsatz: OBS stösst einen Vorgang bei einem Fremdsystem an (Bezahldienst,
Versanddienstleister) und gibt diesem eine Rückruf-Adresse mit, die nur '''ein
einziges Mal''' gültig ist. Damit kann die Adresse nicht später erneut - oder von
jemand anderem - benutzt werden.

Ablauf:

# OBS legt einen Eintrag in <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, dessen Feld '''WebHook''' (<code>re_webhook</code>) auf diesen Eintrag zeigt. Ein Skript wird für diesen Endpunkt nicht gepflegt.
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
# Das Fremdsystem ruft die Adresse auf. Der Server legt den übergebenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code> ab, antwortet mit <code>{"status": "ok"}</code> und '''löscht den Endpunkt'''.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.

{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
normalen Endpunkt mit Skript anlegen.}}

OBS/Kostenpflichtige Module/RESTServer/Scripting

2026-09-15T10:00:28Z

Rademacker:

{{Kostenpflichtige Module}}

=Anleitung für Endpunkt-Skripte=

Jede Anfrage an einen Endpunkt wird nach erfolgreicher Authentifizierung und Autorisierung an das hinterlegte Skript weitergegeben. Das Skript ist in Object Pascal geschrieben und greift auf die OBS-Bibliothek (DB-Zugriff, Hilfsfunktionen) zu.

==Sicherheitshinweise==

{{Hinweis|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Übergabeparameter dürfen niemals ungeprüft in SQL-Anweisungen eingebaut werden. Werte immer über ''DB_SQLVal'' bzw. Parameter-Bindings absichern, Eingabewerte gegen Whitelists prüfen.}}

* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
* Nur das zurückgeben, was der Konsument wirklich braucht - keine internen IDs, keine Sys-Felder, keine Passwörter.
* Bei Fehlern keine internen Details an den Konsumenten zurückgeben; stattdessen schreibt der Server ohnehin Detail-Einträge in '''RESTSRV_PROTO'''.

==Methoden-Signatur==

Pro HTTP-Methode wird im Skript eine gleichnamige '''Prozedur''' implementiert. Der Server ruft genau die Prozedur auf, die zur Methode des eingehenden Requests passt.

procedure Get (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Patch (oReader: TxRestReader; oWriter: TxRestWriter);

Zwei Handles, kein Rückgabewert: '''oReader''' ist die Anfrage, '''oWriter''' die
Antwort. Beide erzeugt der Server, beide gehören ihm - im Skript wird nichts
angelegt und nichts freigegeben.

{{Achtung|'''DELETE hat keine Skript-Methode.''' <code>Delete</code> ist in der
Skriptsprache eine Standardprozedur (Löschen aus einer Zeichenkette); eine eigene
Prozedur dieses Namens lässt sich nicht übersetzen, und der Fehler nennt nur die
Zeile der Deklaration. Wer einen DELETE-Endpunkt braucht, legt die Methode unter
einem anderen Verb ab oder trennt sie in ein eigenes Skript.}}

Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
Not Allowed''' (<code>METHOD_NOT_ALLOWED</code>) und nennt im Header
<code>Allow</code> die Verben, die dieses Skript tatsächlich anbietet - die Liste
stammt aus dem kompilierten Skript und kann deshalb nicht veralten:

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT

Ein im Vertrag zugesagtes Verb braucht also seine Prozedur. Fehlt sie, ist das an
der Antwort sofort zu erkennen und '''kein''' Serverfehler.

==Die Anfrage lesen: oReader==

''oReader'' ist der einzige Zugang zur Anfrage - Query, Header, Formularfelder,
Pfadwerte, Token-Claims und Körper. Alles davon sind '''Zeichenketten''' oder
werden über einen typisierten Leser geholt.

{| class="wikitable"
! Aufruf !! Was er liefert
|-
| <code>oReader.Param('kundennr')</code> || Query-Parameter, POST-Parameter (form-urlencoded) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet
|-
| <code>oReader.Path('uid')</code> || Wert eines Platzhalters aus dem Pfad-Template
|-
| <code>oReader.Form('bemerkung')</code> || Formularfeld einer <code>multipart/form-data</code>-Übertragung
|-
| <code>oReader.Claim('tenant')</code> || Custom-Claim des vorgelegten Tokens
|-
| <code>oReader.Subject()</code> || Subject des Tokens (''sub''-Claim)
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests
|-
| <code>oReader.Offset()</code> || UTC-Offset des Servers, z.B. ''+02:00''
|-
| <code>oReader.HasBody()</code> || Wurde überhaupt ein JSON-Körper gesendet?
|}

Filterung durch den Server:

* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
* Werte, die von aussen kommen, können die reservierten Namen nicht besetzen.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.

Zugriff im Skript:

cKundenNr := oReader.Param('kundennr');
if (not Empty(cKundenNr)) then begin
// ...
end;

===Der Körper: Zugriff über Pfade===

Den JSON-Körper liest ''oReader'' über '''Pfade'''. Es gibt keine Unterobjekte im
Skript, keinen Cast, kein ''.Items[i]'' - und damit auch keine Lebensdauer, um die
sich jemand kümmern müsste.

{| class="wikitable"
! Aufruf !! Bedeutung
|-
| <code>oReader.Str('betreff', cWert)</code> || Liest den Wert. '''Rückgabe Boolean''': war das Feld da? Fehlt es, bleibt die Variable unverändert
|-
| <code>oReader.Int('menge', nWert)</code> || dito, Ganzzahl
|-
| <code>oReader.Num('preis', nWert)</code> || dito, Kommazahl. '''Der Dezimalpunkt aus JSON wird richtig gelesen''' - kein ''StrTran'' mehr
|-
| <code>oReader.Bool('aktiv', lWert)</code> || dito, Boolean
|-
| <code>oReader.NumDef('rabatt', nWert, 0)</code> || wie ''Num'', mit Vorgabewert
|-
| <code>oReader.Has('feld')</code> || Ist das Feld vorhanden? (auch bei ''null'')
|-
| <code>oReader.Count('zeiten')</code> || Anzahl Einträge einer Liste, 0 wenn keine Liste
|-
| <code>oReader.IsArr('zeiten')</code> / <code>IsObj('zeiten[0]')</code> || Gestalt prüfen
|-
| <code>oReader.Keys()</code> || Alle Feldnamen der obersten Ebene, in Kommas eingefasst
|}

'''Verschachtelung steht im Pfad''' - Punkt für Felder, eckige Klammern für Listen:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cVon : string;
nAnz : Integer;
nI : Integer;
begin
nAnz := oReader.Count('zeiten');
for nI := 0 to nAnz - 1 do begin
if (oReader.Str('zeiten[' + IntToStr(nI) + '].von', cVon)) then begin
// ... cVon verarbeiten ...
end;
end;
end;
</syntaxhighlight>

{{Hinweis|'''Der Rückgabewert unterscheidet „nicht gesendet" von „leer
gesendet".''' <code>oReader.Str('feld', cWert)</code> liefert bei
<code>"feld": null</code> ''true'' mit leerem Wert und bei fehlendem Feld
''false''. Genau diese Unterscheidung braucht ein PATCH-artiger Aufruf: „Feld
löschen" und „Feld nicht anfassen" sehen sonst gleich aus.}}

Ist gar kein Körper gesendet worden, liefert jeder Leser ''false'' und
''HasBody()'' ist ''false''. Maximale Body-Grösse: 10 MB - bei einem gepackt gesendeten Körper zusätzlich das 400fache der gesendeten Grösse, siehe [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Kompression. Beide Überschreitungen beantwortet der Server mit '''413''', das Skript läuft gar nicht erst an.

===Werte des Servers===

Bei aktiver JWT-Authentifizierung stehen die Token-Claims über den Reader zur
Verfügung. Sie tragen intern weiterhin die Namen mit Präfix '''_OBS_''' - im
Skript werden sie aber über die Zugriffe der Tabelle oben gelesen und nicht mehr
über den Namen:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_JWT_ID')</code> || JWT-Id (''jti''-Claim) - typisch die User-Id. '''Muss nicht eindeutig sein''': die Sitzung führt der Server über eigene Kennungen (siehe unten)
|-
| <code>oReader.Subject()</code> || Subject (''sub''-Claim) - typisch Benutzername
|-
| <code>oReader.Param('_OBS_JWT_AUDIENCE')</code> || Audience (''aud''-Claim) - typisch Mandant / Rolle
|-
| <code>oReader.Claim('tenant')</code> || Beliebiger Custom-Claim des Tokens, hier ''tenant''; im Folge-Skript lesbar
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}

Unabhängig von JWT stehen ausserdem immer zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_SERVER_TIME')</code> || Aktuelle Serverzeit als ISO-8601 '''mit UTC-Offset''' (z.B. ''2026-08-17T09:12:33+02:00''). Nützlich, um Datumswerte in derselben Zeitzone auszuliefern, in der der Server arbeitet, und damit ein Client seinen Uhren-Versatz bestimmen kann
|-
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+02:00''. Er geht in die Zeitfunktionen (siehe [[#Zeitangaben auf der Leitung|Zeitangaben]])
|-
| <code>oReader.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden (''JWT-Exp'' × 60). Damit kann ein Konfigurations-Endpunkt denselben Wert ausliefern, den der Token wirklich hat
|}

Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.

Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
''oReader.Claim('sid')'' und ''oReader.Claim('rid')'':

{| class="wikitable"
! Claim !! Inhalt
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
|}

Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Skripts gesetzt - ein Skript kann sie also auch mit einem eigenen Claim ''sid''
nicht überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.

===Pfad-Parameter===

Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte über ''oReader.Path'' bereit:

{| class="wikitable"
! Template !! Zugriff im Skript
|-
| <code>/orders/{uid}</code> || <code>oReader.Path('uid')</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>oReader.Path('uid')</code>, <code>oReader.Path('code')</code>
|}

Diese Werte kommen aus dem Routing und sind durch den Client nicht fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].

===Datei-Uploads===

Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), nimmt der Server
hochgeladene Dateien entgegen, legt sie in einem temporären Verzeichnis ab und
übergibt dem Skript Pfad, Originalname und Content-Type über den Reader. Das
Skript entscheidet selbst über die weitere Verarbeitung (z.B. DMS-Ablage). Der
Body wird in diesem Fall '''nicht''' als JSON geparst - ''oReader.HasBody()'' ist
''false''. Es gilt nicht das JSON-Body-Limit (10 MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25 MB;
Überschreitung -> 413).

'''Wie die Datei übertragen wurde, spielt für das Skript keine Rolle.''' Beide
Wege - <code>multipart/form-data</code> und der resumable
<code>Content-Range</code>-Upload - liefern dieselben vier Werte. Das
Übertragungsprotokoll samt Header, Statuscodes und Resume-Verhalten steht in
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]:

{| class="wikitable"
! Aufruf !! Inhalt
|-
| <code>oReader.UploadPath()</code> || Vollständiger Pfad zur temporären Datei auf dem Server
|-
| <code>oReader.UploadName()</code> || Originaldateiname
|-
| <code>oReader.UploadType()</code> || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt), kleingeschrieben
|-
| <code>oReader.UploadSha()</code> || SHA-256 der '''gespeicherten''' Datei, hex in Kleinbuchstaben. Damit lässt sich eine vom Client mitgesendete Prüfsumme vergleichen - erst dieser Vergleich macht aus ihr eine Zusicherung
|}

Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''UploadPath()'' und ''UploadName()'' gefüllt
sind, sobald es läuft.

{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}

Zusatzangaben, die im selben Aufruf mitkommen, liest das Skript mit
<code>oReader.Form('<name>')</code> - bei <code>multipart/form-data</code> sind
das die Partien ohne <code>filename=</code>. Ein vollständiges Beispiel zeigt
[[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].

==Die Antwort schreiben: oWriter==

Der Writer schreibt '''sequentiell''': jeder Aufruf hängt ein Feld an, an der
Stelle, an der er steht. Die äussere Klammer der Antwort setzt der Server. Wird
nichts geschrieben, antwortet er mit ''{}''. Content-Type ist
''application/json; charset=utf-8'', der Status 200, sofern das Skript nichts
anderes setzt.

Einfaches Beispiel:

<syntaxhighlight lang="pascal" line>
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
oWriter.Str('wert_string', '123');
oWriter.Int('wert_int' , 456);
end;
</syntaxhighlight>

{| class="wikitable"
! Aufruf !! Ergebnis
|-
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert
|-
| <code>oWriter.StrN('name', cWert)</code> || wie ''Str'', aber '''null''' statt einer leeren Zeichenkette
|-
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl
|-
| <code>oWriter.Num('preis', nWert, 2)</code> || Kommazahl mit fester Stellenzahl. '''Immer mit Dezimalpunkt''', unabhängig von der Locale des Servers
|-
| <code>oWriter.Bool('aktiv', lWert)</code> || ''true'' / ''false''
|-
| <code>oWriter.Null('lat')</code> || ausdrücklich ''null''
|-
| <code>oWriter.ObjBegin('kunde')</code> … <code>oWriter.ObjEnd</code> || Unterobjekt
|-
| <code>oWriter.ArrBegin('dateien')</code> … <code>oWriter.ArrEnd</code> || Liste
|-
| <code>oWriter.RootArr()</code> || Die '''Wurzel''' ist eine Liste statt eines Objekts. Muss vor dem ersten Feld stehen; ein ''ArrEnd'' gibt es dazu nicht
|-
| <code>oWriter.Raw('meta', cJson')</code> || Fertiges JSON-Fragment einbetten. Siehe unten
|}

'''In einer Liste hat ein Eintrag keinen Namen''' - der leere Feldname ist genau
das:

<syntaxhighlight lang="pascal" line>
oWriter.ArrBegin('dateien');
while (not q.EoF) do begin
oWriter.ObjBegin('');
oWriter.Str ('uid' , q.A2C('f_uid'));
oWriter.Int ('bytes' , q.A2I('f_bytes'));
oWriter.StrN('kategorie', AllTrim(q.A2C('f_kat'))); // null wenn leer
oWriter.ObjEnd;
q.Next();
end;
oWriter.ArrEnd;
</syntaxhighlight>

Ein Name in einer Liste und ein fehlender Name in einem Objekt sind beides
'''Strukturfehler'''. Der Server antwortet dann mit '''500''' und nennt die
Stelle im Protokoll - er liefert kein halbes JSON aus. Dasselbe gilt für einen
Stapel, der am Ende der Methode noch offen ist.

{{Hinweis|'''Ein Helfer bekommt den Writer als Parameter''' und schreibt an der
Stelle hinein, an der er aufgerufen wird - er gibt kein Fragment zurück. Damit
steht die Reihenfolge der Antwort im Code und nicht im Zusammenbau:

<code>procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);</code>}}

'''Raw ist der Notausgang und prüft.''' Er parst das Fragment und bettet den
'''Originaltext''' ein; ungültiges JSON gibt einen Serverfehler, der das Feld
nennt. Gebraucht wird er für ein gespeichertes, '''signiertes''' Dokument:
Parsen und Neuserialisieren würde die signierte Feldreihenfolge zerstören.

===Zeitangaben auf der Leitung===

Zeitstempel gehen als '''ISO-8601 mit Offset''' über die Leitung. Die Wandlung
gehört nicht ins Skript - dort saß der Fehler „zwei Stunden zu früh" an drei
Stellen gleichzeitig:

{| class="wikitable"
! Aufruf !! Zweck
|-
| <code>RestIsoFromDate(dWert, cOffset)</code> || OBS-Zeitpunkt -> ''2026-09-09T14:12:00+02:00''. Leerer String bei leerem Datum
|-
| <code>RestDateFromIso(cWert, cOffset)</code> || ISO-Zeichenkette -> OBS-Zeitpunkt in '''Ortszeit des Servers'''
|-
| <code>oReader.Offset()</code> || Der Offset, der in beide hineingeht
|-
| <code>RestOffsetToMinutes(cOffset)</code> || Offset in Minuten, für eigene Rechnungen
|}

==Antwort steuern: Statuscode, Header, traceId==

Statuscode, Header und das Sperren einer Sitzung laufen über eigene Aufrufe des
Writers, '''nicht''' über Felder im Körper.

{| class="wikitable"
! Aufruf !! Wirkung
|-
| <code>oWriter.Status(201)</code> || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200
|-
| <code>oWriter.Header('ETag', '7')</code> || Beliebiger Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen und Werten werden entfernt (Schutz vor Header-Injection)
|-
| <code>oWriter.NoBody()</code> || Kein Körper - für '''204'''
|-
| <code>oWriter.JwtRevoke('session')</code> || Sperrt die Sitzung des vorgelegten Tokens (''session'') oder alle Sitzungen des Subjects (''all''). Damit wird ein Endpunkt zum Logout, ohne eigene Verwaltung. Scheitert das Sperren, antwortet der Server mit '''503''' statt mit der Antwort des Skripts - siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Abschnitt Abmelden
|-
| <code>oWriter.Error(422, 'VALIDATION_FAILED', 'Feld „menge" fehlt')</code> || Fertige Fehlerantwort in der Form des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]]
|-
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer? Für einen Verteiler, der danach noch etwas anhängen will
|-
| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> || Statt eines JSON-Körpers eine '''Datei''' ausliefern. Die Datei bleibt liegen, der Download ist wiederaufsetzbar. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
|-
| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> || Wie <code>SendFile</code>, aber die Datei wird nach dem Senden '''gelöscht''' und der Download ist nicht wiederaufsetzbar - für Ergebnisse, die je Abruf entstehen (CSV-Export, Report)
|}

Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oReader.TraceId()'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

Setzt ein Skript den Header '''Content-Encoding''' selbst - etwa weil es einen bereits gepackten Körper ausliefert -, hält sich die Engine heraus und packt die Antwort nicht noch einmal. Ohne diesen Header entscheidet der Server selbst, ob gzip zum Einsatz kommt.

===Beispiel: Anlegen mit 201, Location und ETag===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueUid: string;
begin
// ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...

oWriter.Str('uid', cNeueUid);
oWriter.Status(201);
oWriter.Header('Location', '/v1/orders/' + cNeueUid);
oWriter.Header('ETag' , '1');
end;
</syntaxhighlight>

===Beispiel: Strukturierter Fehler mit Statuscode und traceId===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var nMenge: Integer;
begin
if (not oReader.Int('menge', nMenge)) then begin
// Statuscode, code, message, uid und traceId in EINEM Aufruf - dieselbe
// Huelle, die auch die Server-eigenen Fehler tragen.
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

===Beispiel: Optimistic Concurrency (ETag / If-Match)===

Mit Statuscode, Headern und dem lesbaren Header ''If-Match'' führt das Skript je Datensatz einen Versionszähler und lehnt veraltete Schreibzugriffe mit 409 ab:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var nAktuell: Integer;
nIfMatch: Integer;
begin
nAktuell := AuftragVersion(oReader.Path('uid'));
nIfMatch := iVal(oReader.Param('if-match'));

if (nIfMatch <> nAktuell) then begin
// Der ETag gehoert AUCH an die Ablehnung - sonst kennt der Client den
// gueltigen Wert nicht und sein naechster Versuch scheitert wieder.
oWriter.Header('ETag', xStr(nAktuell));
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geaendert');
exit;
end;

// ... speichern, Version hochzählen ...
oWriter.Header('ETag', xStr(nAktuell + 1));
end;
</syntaxhighlight>

==Idempotenz - was das Skript beachten muss==

Sendet ein Konsument bei ''POST''/''PUT''/''PATCH''/''DELETE'' den Header
<code>Idempotency-Key</code>, fängt der '''Server''' doppelte Sendungen ab. Das
Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine
Prüfung am Anfang der Methode.

Was das Skript wissen muss:

{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
|-
| '''2xx''' || Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
|-
| '''5xx''' oder Exception || Der Schlüssel bleibt belegt, der Fall wird protokolliert. Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist
|}

Daraus folgen zwei Regeln für Endpunkt-Skripte:

* '''Fachliche Ablehnungen als 4xx melden''' (422, 409, 404), nicht als 2xx mit Fehlertext im Body. Sonst wird die Ablehnung gespeichert und der Konsument bekommt sie bei jedem weiteren Versuch erneut - auch nachdem er den Fehler behoben hat.
* '''Die Antwort muss vollständig sein.''' Was zurückgegeben wird, wird eingefroren. Ein Feld, das erst der zweite Aufruf ergänzen würde, kommt beim Konsumenten nie an.

Der vollständige Ablauf und die Statuscodes stehen unter
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==JWT-Authentifizierungs-Skript==

Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
cPass: string;
begin
// Eingangsdaten lesen
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

// Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
if (PasswortPasst(cUser, cPass)) then begin
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_AUDIENCE', 'mandant1');
end else begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Login fehlgeschlagen');
end;
end;
</syntaxhighlight>

{{Hinweis|'''Im Anmeldeskript bleiben die _OBS_JWT_*-Felder Felder der
Antwort''' - anders als Status und Header, die zu Aufrufen des Writers geworden
sind. Der Grund: die Token-Ausstellung liest sie aus dem fertigen Körper, und
genau dort erwartet sie sie. Geschrieben werden sie deshalb wie jedes andere
Feld, nur eben mit dem Writer.}}

Rückgabewerte:

{| class="wikitable"
! status !! Bedeutung
|-
| 1 || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
|-
| 9 || Misserfolg, der Server antwortet mit '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
|}

{{Hinweis|Der Text aus ''error'' geht bei ''status'' = 9 '''an den Konsumenten'''
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Endanwender verständlich sein und keine internen Details verraten.}}

Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
„Passwort falsch" erscheinen.

Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.

===Aufbau der Token-Antwort===

Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
Feldern, die das Skript zurückgibt''':

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...",
"accessToken": "eyJ...",
"refreshToken":"eyJ...",
"expiresIn": 28800,
"serverTime": "2026-08-17T09:12:33+02:00"}

{| class="wikitable"
! Feld !! Herkunft
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
|-
| serverTime || Serverzeit ISO-8601 mit Offset
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
|}

Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.

===Custom-Claims, serverTime und Refresh===

Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:

{| class="wikitable"
! RÜckgabefeld !! Bedeutung
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als <code>oReader.Claim('<name>')</code>.
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
|}

Jedes Token trägt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh'') sowie die Sitzungskennungen ''sid'' und ''rid'' des Servers. Die Antwort enthält bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusätzlich ''refreshToken'':

{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}

{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''oReader.Claim(…)''), nie aus Body oder Query.}}

====Refresh-Methode====

Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
(Signatur, Ablauf, ''token_use=refresh'') und in der Sitzung '''entwertet'''.
Einmalgebrauch, Rotation und Sperrliste sind damit Sache des Servers. Das Skript
liefert nur noch die aktuellen Claims - genau das ist der Sinn des Aufrufs: eine
zwischenzeitlich geänderte Rolle oder ein gewechselter Mandant wirken spätestens
mit der nächsten Erneuerung.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal - einmal im Skript, einmal im
Server - und riskiert, dass beide Seiten unterschiedlicher Meinung sind. Der
Server sieht die Skript-Tabelle nicht, und das Skript sieht die Sitzung nicht.}}

Ein bereits benutztes Refresh-Token wird mit '''401''' abgelehnt. Erfolgt die
erneute Vorlage innerhalb von 60 Sekunden, bleibt die Sitzung bestehen (paralleler
Refresh einer App); danach gilt sie als Wiedervorlage und die '''gesamte Sitzung
wird gesperrt'''. Details in [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

Das alte Refresh-jti steht weiterhin als ''oReader.Param('_OBS_JWT_ID')'' bereit,
falls das Skript es für eigene Protokollierung braucht.

<syntaxhighlight lang="pascal" line>
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
begin
cUser := oReader.Subject();

// Der Server hat das vorgelegte Refresh-Token bereits geprueft und
// entwertet. Hier wird nur entschieden, ob der Benutzer die Sitzung
// fortsetzen darf - und mit welchen Rechten.
if (not BenutzerAktiv(cUser)) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
exit;
end;

// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das neue Refresh-Token aus
end;
</syntaxhighlight>

===Abmelden (Logout)===

'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Phase 4.

Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
'''gewöhnlichen Endpunkt''' und setzt dort ''_OBS_JWT_REVOKE''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
GeraeteRegistrierungLoeschen(oReader.Subject());

// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('session');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
abgemeldet, während sein Token weiterläuft.

==Fehlerbehandlung im Skript==

Tritt im Skript eine Exception auf oder schlägt die Syntax-Prüfung fehl, antwortet der Server mit 500 ''Interner Fehler'' und protokolliert die Detail-Meldung in '''RESTSRV_PROTO''' (mit Skript-Fehlertext). Der Konsument sieht keine internen Details.

Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Für einen spezifischen Fehler an den Konsumenten gibt es '''einen''' Aufruf. Er
baut dieselbe Hülle, die auch die Server-eigenen Fehler tragen - Statuscode,
''code'', ''message'', ''uid'' und ''traceId'' -, sodass beide Wege nicht
auseinanderlaufen können:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
if (Empty(oReader.Param('kundennr'))) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

{{Hinweis|'''Error verwirft einen schon begonnenen Körper''' und setzt seinen
eigenen. Ein Skript darf also getrost Felder schreiben und danach noch
abbrechen - was der Client sieht, ist die Fehlerantwort. Nur ein '''offener
Stapel''' (ein ''ObjBegin'' ohne ''ObjEnd'') bleibt auch dann ein Strukturfehler.}}

{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
Body auszuwerten - und nur so gibt der Server einen belegten
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}

===Ändern: qSqlInit statt qSqlRead===

Zum '''Ändern''' eines vorhandenen Satzes wird ebenfalls <code>qSqlInit</code>
benutzt - der Satz wird über <code>sys_uid</code> adressiert:

<syntaxhighlight lang="pascal" line>
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cSysUid); // Schreib-Index auf den Originalsatz
q.qSet('ti_status', '9');
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln, siehe unten
end;
qSqlFree(q);
</syntaxhighlight>

<code>qSqlRead</code> ist dafür die falsche Wahl, aus zwei Gründen:

* Es liest den '''kompletten Altsatz''' ein - ein zusätzlicher Lesezugriff, der Zeit kostet.
* Es schreibt anschliessend nur die '''Änderungen'''. Ist der neue Wert gleich dem alten, entsteht gar kein Write, und <code>SaveData</code> liefert '''False''' - ununterscheidbar von einem echten Fehlschlag.

{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen'''
Datensatz an, statt den vorhandenen zu ändern. Die <code>sys_uid</code> ist der
Schreib-Index und gehört bei jeder Änderung gesetzt.}}

Damit entfällt auch das übliche Paar aus <code>DB_LSeek</code> und
<code>qSqlRead</code>: '''eine''' Abfrage auf die <code>sys_uid</code> liefert
zugleich die Existenzprüfung und den Schreib-Index.

<syntaxhighlight lang="pascal" line>
cUid := '';
if (DB_SOpen(oDB, 'SELECT sys_uid FROM tickets WHERE ' + cWhere + ' LIMIT 1', q)) then begin
if (not q.EoF) then begin
cUid := q.A2UID();
end;
end;
DB_Close(q);

if (not Empty(cUid)) then begin
// ändern: qSqlInit + sys_uid
end else begin
// anlegen: qSqlInit ohne sys_uid
end;
</syntaxhighlight>

===Mehrere Felder sind EIN Schreibvorgang===

Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> entgegen
und schreibt sie mit '''einem''' <code>SaveData</code>. Fallen an derselben
Zeile mehrere Felder an, gehören sie in dasselbe Objekt:

<syntaxhighlight lang="pascal" line>
// FALSCH: fünf Felder, fünf Schreibvorgänge - und jeder Setzer, der sich
// seine sys_uid selbst holt, bringt zusätzlich eine eigene Abfrage mit
FeldSetzen(cUid, 'ti_status' , '9');
FeldSetzen(cUid, 'ti_grund' , cGrund);
FeldSetzen(cUid, 'ti_von' , cBenutzer);

// RICHTIG: ein Schreibobjekt, ein SaveData
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cUid);
q.qSet('ti_status', '9');
q.qSet('ti_grund' , cGrund);
q.qSet('ti_von' , cBenutzer);
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln
end;
qSqlFree(q);
</syntaxhighlight>

Das ist nicht nur eine Frage der Geschwindigkeit: einzeln geschriebene Felder
sind '''nicht atomar'''. Bricht der dritte Schreibvorgang ab, steht die Zeile
halb geändert da - Grund gesetzt, Zeitpunkt nicht.

Wird nichts gesetzt, darf auch nicht geschrieben werden: das Schreibobjekt dann
mit <code>qSqlFree</code> freigeben, statt ein leeres <code>SaveData</code>
abzusetzen.

{{Hinweis|Ein Setzer für '''ein''' Feld (<code>FeldSetzen(cUid, cFeld, cWert)</code>)
ist bequem und deshalb verführerisch. Er versteckt aber je Aufruf eine eigene
Abfrage und ein eigenes <code>SaveData</code>. Für einen Vorgang mit mehreren
Feldern gehört ein '''Editier-Helfer''' her, der das Schreibobjekt liefert -
geschrieben wird einmal am Ende.}}

===Keine Abfrage je Zeile===

Was in einer Liste je Zeile nachgeschlagen wird, kostet '''N''' Abfragen für
'''eine''' Antwort. Bei fünfzig Aufträgen sind das fünfzig Abfragen für ein
einziges Feld. Der Ausweg ist immer derselbe:

* Werte aus einer 1:1-Beziehung über einen <code>LEFT JOIN</code> mitnehmen - bei einem '''eindeutigen''' Index auf dem Join-Feld kann er die Zeilen nicht vervielfachen.
* Einzelwerte aus einer 1:n-Beziehung über eine '''Unterabfrage''' in der SELECT-Liste holen, nicht über einen Join (der Join würde die Zeilen vervielfachen).
* Eine echte Unterliste (Positionen, Dateien) nur dann nachladen, wenn ein '''Zählfeld''' in der Hauptabfrage sagt, dass es überhaupt eine gibt.

{{Hinweis|Ein GET soll '''lesen'''. Schreibvorgänge im Lesepfad - etwas
"beim ersten Ausliefern festschreiben" - vervielfachen sich mit der Zeilenzahl
und treffen den Aufrufer, der nur eine Liste angefordert hat.}}

===Schreibfehler erkennen===

'''<code>SaveData</code> liefert einen Boolean - und der ist die einzige
Fehlermeldung, die es gibt.''' (Auch der '''Parameter''' ist ein Boolean:
''NEW_RECORD'' und ''UPDATE_RECORD'' sind Wahrheitswerte, keine Zahlen.) Schlägt das Schreiben in der Datenbank fehl
(''Duplicate entry'' auf einem eindeutigen Index, zu langer Wert, fehlende
Spalte), dann

* wird '''keine''' Exception ausgelöst,
* steht '''nichts''' in ''RESTSRV_PROTO'',
* läuft das Skript weiter und antwortet mit dem Erfolg, den es selbst formuliert.

Wer den Aufruf als Anweisung schreibt, baut damit einen stillen Datenverlust ein.
Weil in einem Endpunkt schnell ein Dutzend Schreibvorgänge zusammenkommen, gehört
die Prüfung in eine eigene kleine Prozedur - am besten in die gemeinsame Lib:

<syntaxhighlight lang="pascal" line>
procedure Speichern(q: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
begin
lOk := q.SaveData(lNeu);
qSqlFree(q); // auch im Fehlerfall freigeben
if (not lOk) then begin
raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
end;
end;

// Aufruf statt SaveData + qSqlFree:
q := qSqlInit(oDB, 'tickets');
q.qSet('ti_betreff', cBetreff);
Speichern(q, NEW_RECORD, 'Ticket');
</syntaxhighlight>

Die Exception fängt der Server: er schreibt ''Schreiben fehlgeschlagen: Ticket''
nach '''RESTSRV_PROTO''' und antwortet mit '''500'''. Liegt ein
''Idempotency-Key'' an, wird er dabei '''freigegeben''' - die Anfrage ist also
wiederholbar (siehe Abschnitt Idempotenz).

{{Hinweis|Ein fehlgeschlagenes Schreiben ist kein Fall, in dem ein Endpunkt
sinnvoll weiterlaufen kann: die Fachwirkung ist dann unvollständig. Wer trotzdem
weitermachen will - etwa weil mehrere unabhängige Sätze geschrieben werden -,
prüft den Rückgabewert und baut selbst eine Antwort. Ignorieren darf man ihn
nie.}}

Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.

==Gemeinsamen Code auslagern==

Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:

<pre>
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</pre>

{| class="wikitable"
! Attribut !! Bedeutung
|-
| '''T''' || Tabelle, aus der geladen wird
|-
| '''I''' || Spalte, über die gesucht wird
|-
| '''V''' || Wert, der in dieser Spalte stehen muss
|-
| '''F''' || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}

Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Compiler sieht danach den zusammengesetzten Text - eine Funktion aus der Lib lässt
sich also aufrufen wie eine im Skript selbst geschriebene.

===Bewährtes Muster: Lib als eigene Endpunkt-Zeile===

Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
RESTSRV_ENDPOINTS''' abzulegen:

# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
# Den Lib-Quelltext ins Skript-Feld dieser Zeile schreiben (F7).
# '''Keine Berechtigung''' in der Berechtigungs-Liste vergeben - das ist der Schutz: ohne Berechtigung beantwortet der Server einen Aufruf mit 403.
# In jedem nutzenden Endpunkt die Direktive oben einfügen.

Damit ist die Lib reiner Ablageort und von aussen nicht nutzbar. Eine Änderung
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
angefasst werden muss.

{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Funktion hinzu, genügt es nicht, nur das nutzende Skript zu aktualisieren. Eine
ältere Lib lädt fehlerfrei - der Compiler meldet dann ausschliesslich die neuen
Namen als ''Unknown name'', was leicht wie ein Fehler im Skript aussieht.}}

{{Hinweis|Auch hier greift der Endpunkt-Cache: eine Änderung an der Lib wird erst
nach Ablauf des TTL (bis zu 60 Sekunden) wirksam.}}

===Wohin gehört welcher Code?===

Drei Ebenen, und die Zuordnung entscheidet, wie schnell eine Änderung wirkt:

{| class="wikitable"
! Art des Codes !! Wohin !! Wirksam
|-
| Fachlogik **einer** Anwendung - Feldnamen, Zustandswerte, Rollenregeln, Schreibziele || in die '''DWS-Lib dieser Anwendung''' (eigene Endpunkt-Zeile, per <code>{$L …}</code> eingebunden) || nach Ablauf des Cache-TTL, ohne Build
|-
| Mechanik, die '''mehrere''' Anwendungen brauchen - und auch das OBS-Umfeld || nach '''obs_lib''' als Delphi-Unit || erst nach Build und Rollout
|-
| Mechanik, die '''nur''' der REST-Server braucht || in die Units des Servers || erst nach Build und Rollout
|}

Die Regel hat einen praktischen Grund und keinen ästhetischen: Fachlogik ändert
sich in Tagen, Mechanik in Monaten. Was in der Lib liegt, ist nach einer Minute
aktiv; was in einer Unit liegt, braucht einen Build. Wer Fachlogik nach unten
schiebt, tauscht Geschwindigkeit gegen nichts ein.

{{Hinweis|Eine Anwendung, die ihre eigene Lib hat, kopiert sie '''nicht''' von
einer anderen. Zwei Kopien derselben Lib driften auseinander, und die Abweichung
fällt erst auf, wenn eine der beiden Anwendungen etwas Falsches tut. Geteiltes
gehört eine Ebene tiefer.}}

==Fallstricke im Skript==

Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:

{| class="wikitable"
! Stolperstein !! Richtig
|-
| ''DB_SOpen('Y00…', oDB, …)'' - der AD-UID-Parameter aus dem Delphi-Code || Im Skript '''ohne UID''': <code>DB_SOpen(oDB, cSql, q)</code>. Gleiches gilt für <code>qSqlInit(oDB, 'tab')</code> und <code>qSqlRead(oDB, 'tab', cWhere)</code> - jede dieser Funktionen beginnt mit ''oDB''
|-
| ''oReader.Str<T>(…)'' oder irgendein Generic || Generics gibt es in der Skriptsprache nicht. Die Leser sind je Typ eigene Methoden: ''Str'', ''Int'', ''Num'', ''Bool''
|-
| Eine eigene Prozedur ''Delete'' für DELETE || ''Delete'' ist eine '''Standardprozedur''' der Sprache. Die Deklaration lässt sich nicht übersetzen, und die Meldung nennt nur die Zeile - nicht die Ursache
|-
| Ein Helfer, der ein JSON-Fragment als String zurückgibt || Den '''Writer als Parameter''' übergeben und an der richtigen Stelle hineinschreiben. Fragmente von Hand zusammenzusetzen ist genau der Weg, auf dem die Reihenfolge und die Klammern verloren gingen
|-
| ''oWriter.ArrEnd'' nach ''RootArr'' || ''RootArr'' öffnet '''keine''' Ebene, es bestimmt nur die Klammer der Wurzel. Ein ''ArrEnd'' dazu ist ein Strukturfehler
|-
| Zahlen selbst formatieren (''NStr'', ''StrTran'') || <code>oWriter.Num('preis', nWert, 2)</code>. Selbst formatiert stand bei Werten ab 1000 der Tausendertrenner im JSON - gültiges JSON, falscher Wert, keine Meldung
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'|' + wert + '|'</code>) und mit ''Pos'' prüfen
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
|-
| <code>q.SaveData(…)</code> als Anweisung schreiben || ''SaveData'' liefert einen '''Boolean'''. Ein SQL-Fehler beim Schreiben wirft '''keine''' Exception und landet in '''keinem''' Protokoll - der Rückgabewert ist die einzige Meldung. Immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Je Feld ein eigener Setzer-Aufruf || Ein <code>qSqlInit</code>-Objekt, beliebig viele <code>qSet</code>, '''ein''' <code>SaveData</code>. Einzeln geschrieben kostet jedes Feld eine eigene Abfrage samt eigenem Write - und der Vorgang ist nicht mehr atomar, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Ein Wert je Zeile nachgeschlagen || In einer Liste sind das N Abfragen für eine Antwort. Über <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n) mitnehmen, siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]]
|-
| Ausgabeparameter vom Typ <code>var … : TDateTime</code> || Bringt die Skript-VM zum '''Absturz''' (Assertion in ''dwsStack.pas''), und zwar beim ersten '''Lesen''' des Werts - nicht schon beim Schreiben, die Ursache liegt also nicht dort, wo der Fehler auffällt. <code>var string</code>, <code>var Integer</code> und <code>var Double</code> laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und erst beim Aufrufer wandeln
|}

==Skript-Cache==

Der Server cached das kompilierte Skript pro Endpunkt (Schlüssel: ''sys_date'' des Endpunkts). Zusätzlich werden die Endpunkt-Definitionen pro Server-Profil in einem TTL-Cache (Standard 60 s) gehalten. Eine Skript-Änderung über F7 wird daher erst nach Ablauf dieses TTL (bzw. nach einer Cache-Invalidierung) wirksam - typischerweise innerhalb einer Minute, nicht zwingend sofort.

==Verfügbare Bibliotheken==

Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:

* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
* ''Base.qSqlReg'' - Schreibzugriffe
* ''lib_ScriptIO'' - Writer und Reader, siehe unten. '''System.JSON braucht ein Endpunkt-Skript nicht''' - der Writer erzeugt die Antwort, der Reader liest den Körper
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''
* ''lib_ScriptIO'' - ''TxRestWriter'', ''TxRestReader'' und die Zeitfunktionen ''RestIsoFromDate'' / ''RestDateFromIso'' / ''RestOffsetToMinutes''. Writer und Reader bekommt das Skript als Parameter; die Zeitfunktionen ruft es direkt

Die wichtigsten Aufrufe mit ihren Skript-Signaturen:

{| class="wikitable"
! Zweck !! Aufruf
|-
| Lesen || <code>DB_SOpen(oDB, cSql, q)</code>, dann <code>q.EoF</code>, <code>q.Next()</code>, <code>q.A2C('feld')</code> / <code>A2I</code> / <code>A2F</code> / <code>A2D</code> / <code>A2UID()</code>, am Ende <code>DB_Close(q)</code>
|-
| Neu anlegen || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('feld', wert)</code>, <code>if (not q.SaveData(NEW_RECORD)) then …</code>, <code>qSqlFree(q)</code> – der Rückgabewert ist Pflicht, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Ändern || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('sys_uid', cUid)</code>, <code>q.qSet(…)</code>, <code>if (not q.SaveData(UPDATE_RECORD)) then …</code>, <code>qSqlFree(q)</code> – '''nicht''' <code>qSqlRead</code>, siehe [[#Ändern: qSqlInit statt qSqlRead|Ändern]]. Alle Felder derselben Zeile in '''ein''' Objekt, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
|-
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
|}

{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
Skript nicht übersetzen.}}

Konkrete Beispiele:

* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

OBS/Kostenpflichtige Module/RESTServer

2026-09-15T10:00:17Z

Rademacker:

{{Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

Der REST-Server ist die '''universelle Schnittstelle''' Ihrer OBS-Installation nach außen. Er macht aus Ihrem OBS einen Dienst, mit dem andere Programme - Webseiten, Apps, Geräte, Kundensysteme, Cloud-Dienste - direkt sprechen können. Statt Daten manuell zu exportieren, zu mailen oder über Umwege bereitzustellen, holen sich angebundene Systeme genau die Information, die sie brauchen, in dem Moment, in dem sie sie brauchen - oder liefern neue Daten direkt in OBS ab.

Für Anwender, die nicht selbst programmieren, bedeutet das: '''Was bisher nur manuell, per Datei-Import oder über Spezialschnittstellen ging, lässt sich jetzt automatisieren.''' Eine Webseite zeigt live aktuelle Lagerbestände. Mitarbeiter erfassen Zeiten über das Handy, ohne dass jemand Excel-Listen einpflegen muss. Ein Kunde stößt per Bestelltaste in seinem System einen Vorgang in Ihrem OBS an. Ein Lieferant meldet Wareneingänge automatisch zurück. Jeder dieser Anwendungsfälle wird einmal eingerichtet und läuft danach automatisch.

Technisch gesehen ist der REST-Server ein in OBS integrierter, voll konfigurierbarer '''HTTP/HTTPS-Dienst''', dessen Endpunkte über in OBS gepflegte Pascal-Skripte realisiert werden. Jeder Endpunkt bekommt eine eigene Adresse, eine eigene Logik und eine eigene Berechtigungsstruktur. Rückgaben erfolgen ausschliesslich im JSON-Format. Damit lassen sich beliebige Lese- und Schreibvorgänge auf der OBS-Datenbank realisieren, ohne dass externe Systeme direkten Datenbank-Zugriff erhalten - das ganze OBS-Regelwerk (Rechte, Validierung, Geschäftslogik) bleibt aktiv.

Im Ergebnis ist der REST-Server kein einzelnes Feature, sondern ein '''Werkzeugkasten''': Was an Daten oder Funktionen in OBS verfügbar ist, kann über den REST-Server auch nach außen angeboten - oder von außen entgegengenommen - werden. Die Bandbreite reicht vom einfachen Lese-Endpunkt für ein Webseiten-Widget bis hin zu kompletten B2B-Integrationen mit Mandanten- und Rollen-Trennung.

Aufruf des Moduls in OBS:
'''Stammdaten''' -> '''Z Weitere Stammdaten''' -> '''REST-Server'''

==Anwendungsbereiche==

Die folgenden Einsatzfälle sind typische Beispiele, an denen sich der praktische Nutzen ablesen lässt. Es ist keine abschliessende Liste - alles, was sich in OBS-Skripten abbilden lässt, kann auch über einen Endpunkt bereitgestellt werden.

{{Hinweis|Dies sind Beispiele. Für die konkrete Entwicklung können, je nach Komplexität, weitere Kosten anfallen.}}

===Webseiten und Kundenportale===

* '''Live-Daten auf der eigenen Webseite:''' Lagerbestände, Verfügbarkeiten, Preise, Auftragsstatus aus OBS direkt anzeigen, ohne tägliche Datei-Exports.
* '''Kundenportale:''' Kunden sehen ihre offenen Posten, Auftragshistorie, Lieferscheine. Die Seite holt sich die Daten zur Anzeigezeit direkt aus OBS, jeder Kunde sieht nur seine eigenen Daten.
* '''Trackingseiten:''' Status einer Bestellung, eines Auftrags oder einer Reparatur für Endkunden, abrufbar über eine Sendungsnummer.

===Mobile Anwendungen und Außendienst===

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''QR-/Barcode-Scanner und Lagergeräte:''' Wareneingang, Inventur, Kommissionierung direkt in OBS abbilden, ohne zwischengeschaltete Software.
* '''Außendienst-Apps:''' Techniker sehen ihre Aufträge, dokumentieren Einsätze, erfassen Material - synchronisiert mit OBS.

===Anbindung von Drittsystemen===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''Buchhaltungs- und ERP-Systeme:''' Bidirektionaler Austausch von Belegen, Stammdaten und Buchungen.
* '''CRM- und Marketing-Tools:''' Personendaten, Aktivitäten oder Mailing-Empfänger werden synchron gehalten.
* '''Logistikdienstleister:''' Versandaufträge werden übergeben, Tracking-Informationen zurückgeliefert.

===Automatisierte Rückmeldungen (WebHooks)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''Versanddienste:''' Statusmeldungen (verschickt, zugestellt, retour) werden direkt im passenden Vorgang dokumentiert.
* '''Cloud-Workflows:''' Externe Automatisierungs-Plattformen (Make, Zapier, n8n, ...) stoßen OBS-Vorgänge an oder werden von OBS aus angesprochen.

===Geschäftspartner-Kommunikation (B2B)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''Kunden-Schnittstelle:''' Grosskunden bestellen direkt aus ihrem ERP heraus, Stammdaten und Konditionen werden zentral gepflegt.
* '''Sichere Maschine-zu-Maschine-Kommunikation:''' Mit Mutual-TLS (mTLS) wird sichergestellt, dass nur die freigeschalteten Partnersysteme - und niemand sonst - mit OBS sprechen können.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''Verbindung mehrerer Standorte:''' Verteilte Systeme tauschen Daten über definierte Endpunkte aus, ohne offene Datenbankverbindungen.
* '''Datenbereitstellung für Dashboards und Auswertungen:''' BI-Tools (Power BI, Grafana, ...) lesen aufbereitete Kennzahlen direkt aus OBS.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''Fehler werden weniger.''' Jede manuelle Stelle ist eine mögliche Fehlerquelle; jede Automatisierung eine Stelle, an der nichts mehr schiefgehen kann.
* '''Neue Geschäftsmodelle werden möglich.''' Kunden- und Lieferantenportale, Self-Service-Funktionen, App-Anbindungen lassen sich aufbauen, ohne ein zweites System pflegen zu müssen.
* '''Bestehende Software bleibt verbunden.''' Statt eine vorhandene Anwendung ablösen zu müssen, kann sie über den REST-Server an OBS angedockt werden - in beiden Richtungen.
* '''Skaliert mit:''' Was klein anfängt (ein einzelner Endpunkt für eine Webseite) kann zu einer kompletten Integrations-Plattform ausgebaut werden, ohne dass die Grundlage gewechselt werden muss.

==Architektur im Überblick==

Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:

{| class="wikitable"
! Baustein !! Tabelle !! Zweck
|-
| Server || RESTSRV_SERVER || TLS-Profil + eigene HTTP-Server-Instanz, kann mehrfach existieren
|-
| Bindung || RESTSRV_BINDINGS || IP-Adresse + Port pro Server
|-
| Zugang || RESTSRV_ACCOUNT || API-Key, optionale Host- und CORS-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| Protokoll || RESTSRV_PROTO || Laufende Ereignisse, Fehler, Audit-Einträge
|-
| Statistik || RESTSRV_STATS || Aufrufzähler, Antwortzeiten und HTTP-Status pro Endpunkt
|}

Eine Anfrage durchläuft folgende Stationen:

# Rate-Limit-Prüfung (pro API-Key bzw. IP und global, Schwellen je Server-Profil)
# Authentifizierung über den API-Key (Header ''apikey'')
# CORS-Prüfung (sofern ''Origin''-Header gesetzt)
# Optional: JWT-Prüfung - Signatur, Ablauf und Sitzung (sofern für den Zugang aktiviert)
# Routing: Auflösung des Pfads über die Pfad-Templates der Endpunkte
# Prüfung der Berechtigung (Zugang -> Endpunkt)
# Idempotenz-Prüfung (nur bei POST/PUT/PATCH/DELETE '''mit''' ''Idempotency-Key''-Header)
# Ausführung des Endpunkt-Skripts (oder WebHook-Antwort)
# Festschreiben des Ergebnisses im Idempotenz-Speicher (sofern in Schritt 7 reserviert)
# JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag

==Adressierung==

Ein Endpunkt wird über ein '''Pfad-Template''' angesprochen, das den Pfad nach dem Host beschreibt und Platzhalter enthalten kann:

http://[Hostadresse][:Port][Pfad-Template]

Beispiele:

https://api.meinserver.de/kalender/v1
https://api.meinserver.de/orders/{uid}
https://api.meinserver.de/orders/{uid}/modules/{code}

Statische Segmente müssen exakt passen; Platzhalter in geschweiften Klammern (z.B. {uid}) matchen einen beliebigen Wert und stehen im Skript als Pfad-Parameter zur Verfügung. Eine Versionskennung wird als statisches Segment ins Template aufgenommen (z.B. /kalender/v1), um eine Funktionalität zu verändern, ohne bestehende Konsumenten zu brechen. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==Unterstützte HTTP-Methoden==

Der Server akzeptiert die Methoden '''GET''', '''POST''', '''PUT''', '''DELETE''' und '''PATCH''' sowie '''OPTIONS''' (CORS-Preflight, ohne Skript-Aufruf). Jede Methode wird im Endpunkt-Skript als gleichnamige Funktion implementiert. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Kompression==

Der Server packt Antworten mit '''gzip''', wenn der Client sie annimmt. Ausgehandelt wird über den Anfrage-Header <code>Accept-Encoding</code>; die Antwort trägt dann <code>Content-Encoding: gzip</code> und <code>Vary: Accept-Encoding</code> - bei einer CORS-Anfrage steht dort <code>Vary: Origin, Accept-Encoding</code>, also '''eine''' Zeile mit beiden Bedingungen. Browser, <code>curl --compressed</code> und die gängigen HTTP-Bibliotheken entpacken selbstständig - für den Konsumenten ändert sich nichts ausser der übertragenen Datenmenge.

Gepackt wird nur, wo es etwas bringt:

* Nur JSON, XML, Text, CSV und SVG. Bereits komprimierte Typen - PDF, Bild, ZIP, Video - werden durch gzip '''grösser''', nicht kleiner.
* Erst ab '''1024 Byte'''. Darunter kostet der gzip-Rahmen mehr, als der Inhalt einspart.
* '''Nicht''' bei Dateiantworten, nicht bei Teilauslieferungen (206) und nicht bei Antworten ohne Körper (204, 304).
* Nicht, wenn das Endpunkt-Skript den Header <code>Content-Encoding</code> selbst gesetzt hat - dann gehört die Antwort dem Skript.

'''deflate''' wird in '''keiner''' Richtung unterstützt. Der Wert ist historisch uneindeutig - die einen senden RFC-1950-gerahmt, die anderen roh -, und wer ihn nennt, beherrscht ohnehin gzip. Eine Anfrage mit <code>Content-Encoding: deflate</code> wird mit 415 abgewiesen.

Abschalten lässt sich das Packen je Server-Profil über den Haken ''Keine Kompression'' (siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]). Der Haken betrifft ausschliesslich die Antwortrichtung.

===Komprimierte Anfragen===

In der Gegenrichtung nimmt der Server '''gzip''' entgegen: Trägt eine Anfrage den Header <code>Content-Encoding: gzip</code>, wird der Körper entpackt, bevor ihn jemand liest. Das Endpunkt-Skript merkt davon nichts.

{| class="wikitable"
! Anfrage !! Antwort
|-
| <code>Content-Encoding</code> fehlt oder <code>identity</code> || normale Verarbeitung; ab 10 MB Körpergrösse '''413'''
|-
| <code>gzip</code> || Körper wird entpackt
|-
| <code>deflate</code>, anderer Wert (z.B. <code>br</code>) oder mehrere Werte || '''415''' <code>UNSUPPORTED_MEDIA_TYPE</code>
|-
| Gepackter Körper bei einem Datei-Upload || '''415''' - siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
|-
| Entpackter Körper über '''10 MB''' || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|-
| Entpackter Körper über dem '''400fachen''' der gesendeten Grösse || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|}

{{Hinweis|Für einen gepackten Anfragekörper gelten '''zwei''' Grenzen. Beide zählen den '''entpackten''' Inhalt, und beide greifen bereits '''während''' des Entpackens - ein Körper, der sie reisst, belegt den Speicher gar nicht erst:

* '''10 MB''' absolut. Dieselbe Grenze, die auch für einen ungepackten Körper gilt.
* '''das 400fache''' der gesendeten Grösse. Damit wird eine ''Dekompressionsbombe'' - wenige Kilobyte, die sich auf Hunderte Megabyte aufblähen - schon nach wenigen Prozent abgebrochen.

Die zweite Grenze trifft normale Nutzlasten nicht. Gemessen erreichen echte JSON-Körper Verhältnisse von 24:1 bis 40:1, und selbst eine Liste aus zehntausenden identischen Zeilen kommt nur auf rund 340:1 - mehr gibt das Verfahren für wiederholte Datensätze nicht her. Über 400:1 kommt nur, wer sehr lange Läufe desselben Zeichens sendet.

Für Datei-Uploads gilt keine der beiden Grenzen - dort zählt allein die je Endpunkt eingestellte Maximalgrösse.}}

==Datei-Uploads==

Endpunkte, die dafür freigeschaltet sind (<code>re_upload</code>), nehmen Dateien
per <code>multipart/form-data</code> oder als fortsetzbaren '''Resumable-Upload'''
(<code>Content-Range</code>) entgegen. Die maximale Grösse wird pro Endpunkt
festgelegt (<code>re_upload_size</code>, Standard 25 MB); Überschreitung
ergibt 413, ein Upload an einen nicht freigeschalteten Endpunkt 415. Der Server
legt die Datei temporär ab und übergibt dem Skript den Pfad; die weitere
Verarbeitung (z.B. DMS-Ablage) übernimmt das Skript. Details:
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Doppelte Sendungen abfangen (Idempotenz)==

Ein Client, der nach einem Timeout dieselbe Anfrage erneut schickt, darf keine
Zweitbuchung auslösen. Der Server erledigt das selbst: Sendet ein Aufruf mit
'''POST''', '''PUT''', '''PATCH''' oder '''DELETE''' den Header
<code>Idempotency-Key</code>, merkt sich der Server Schlüssel und Ergebnis in
'''RESTSRV_IDEMPOTENCY'''. Eine Wiederholung mit demselben Schlüssel und demselben
Inhalt bekommt die '''gespeicherte Antwort''' zurück - das Endpunkt-Skript läuft
gar nicht erst an.

* '''Ohne den Header ändert sich nichts.''' Bestehende Endpunkte verhalten sich unverändert.
* '''Kein Schalter am Endpunkt.''' Die Mechanik greift automatisch, sobald der Header anliegt.
* '''Das Skript muss nichts tun.''' Eine eigene Idempotenz-Logik im Skript ist nicht mehr nötig.

Details und die Statuscodes: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Sitzungen und Abmelden==

Ein JWT trägt seine Gültigkeit in sich: der Server prüft Signatur und Ablauf und
braucht dafür keine Datenbank. Genau deshalb liesse sich ein ausgegebener Token
von sich aus auch nicht mehr zurückziehen - ein verlorenes Gerät wäre bis zum
Ablauf des Tokens weiter nutzbar.

Der Server führt deshalb zu jedem ausgestellten Token-Paar eine Zeile in
'''RESTSRV_TOKEN''' und prüft jeden Zugriff dagegen. Daraus ergeben sich drei
Eigenschaften:

* '''Abmelden wirkt sofort.''' Ein ''DELETE'' auf den JWT-Endpunkt sperrt die Sitzung; alle Token dieser Sitzung sind damit unmittelbar ungültig, auch die noch nicht abgelaufenen. Anmelden, Erneuern und Abmelden laufen also über einen einzigen Endpunkt, und für das Abmelden ist kein Skript nötig.
* '''Ein Refresh-Token gilt genau einmal.''' Beim Erneuern wird es entwertet. Wird es später erneut vorgelegt, gilt das als Diebstahl oder Fehlfunktion: die betroffene Sitzung wird komplett gesperrt und der Vorfall protokolliert.
* '''Alle Geräte abmelden.''' Ein gewöhnlicher Endpunkt kann über das Antwortfeld ''_OBS_JWT_REVOKE'' auch alle Sitzungen eines Benutzers sperren - der Support-Fall „Gerät verloren".

{{Achtung|Mit der Einführung dieser Prüfung verlieren '''alle vorher
ausgestellten Token''' ihre Gültigkeit, weil sie zu keiner Sitzung gehören.
Angemeldete Konsumenten müssen sich nach dem Update einmalig neu anmelden.}}

Der Speicher pflegt sich selbst: Zeilen werden gelöscht, sobald sowohl das
Access- als auch das Refresh-Token abgelaufen sind. Details und die Skript-Seite:
[[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Fehlerformat==

Jede Fehlerantwort des Servers hat dieselbe Form: ein einziges ''error''-Objekt
mit maschinenlesbarem Code, Support-Kennung, Meldung und Korrelations-ID:

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00E2RTPDY",
"message": "Ungültiges oder abgelaufenes Token",
"traceId": "20260817T091233123-00001A"
}
}
</pre>

* '''code''' - sprechender Bezeichner (z.B. ''AUTH_EXPIRED'', ''NOT_FOUND'', ''RATE_LIMITED'', ''INTERNAL_ERROR''), an dem ein Client seine Reaktion festmachen kann, ohne Texte auszuwerten.
* '''uid''' - OBS-Kennung der Codestelle. Für die Support-Recherche gedacht, nicht zur Auswertung im Client.
* '''message''' - Text für den Client. Interne Fehlerdetails stehen nie darin, sondern ausschliesslich im Protokoll '''RESTSRV_PROTO'''.
* '''traceId''' - Korrelations-ID. Steht zusätzlich im Header ''X-Trace-Id'' und in jeder zugehörigen Logzeile.

Ein Endpunkt-Skript kann eigene Codes setzen; siehe
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

{{Achtung|''Fehlercode'', ''Nachricht'' und ''traceId'' stehen '''nur''' im
''error''-Objekt, nicht flach daneben - der Wert von
''Fehlercode'' heisst jetzt ''error.uid'', ''Nachricht'' entspricht
''error.message''. Clients, die die flachen Felder auswerten, müssen angepasst
werden.}}

==Sicherheitsmerkmale==

Der REST-Server enthält eine Reihe von Schutzmechanismen:

* '''Rate-Limit:''' Standardmässig max. 10 fehlgeschlagene und 120 erfolgreiche Anfragen pro API-Key (Account) bzw. IP und 60 Sekunden, max. 600 Anfragen global pro 60 Sekunden. Beim Überschreiten wird HTTP 429 mit ''Retry-After''-Header zurückgegeben. Die vier Schwellen lassen sich '''pro Server-Profil''' hinterlegen; die Zähler laufen ebenfalls getrennt je Profil, ein überlastetes Profil bremst das andere also nicht mit aus. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].
* '''Body-Limit:''' max. 10 MB Request-Body (JSON), max. 1024 Zeichen pro Header- oder Query-Parameter. Datei-Uploads laufen über einen separaten Pfad und sind pro Endpunkt auf <code>re_upload_size</code> MB begrenzt (Standard 25 MB).
* '''Sensible Felder''' (''password'', ''token'', ''secret'', ''apikey'', ''authorization'', ''cookie'', ...) werden in Protokoll-Ausgaben automatisch maskiert.
* '''Widerrufbare Token:''' Jedes ausgestellte Token-Paar gehört zu einer Sitzung in '''RESTSRV_TOKEN''' und wird bei '''jedem''' Zugriff dagegen geprüft. Eine Abmeldung wirkt damit sofort und nicht erst mit dem Ablauf des Tokens; ein Refresh-Token gilt genau einmal. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].
* '''Reserviertes Präfix:''' Parameter-Namen mit Präfix ''_OBS_'' können von aussen nicht gesetzt werden, sie sind für den Server reserviert (z.B. JWT-Claims).
* '''Geblockte Header:''' ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key'' werden nicht an das Skript durchgereicht.
* '''TLS:''' Bei Profilen mit aktivem TLS fährt der Server ohne Zertifikat und Key nicht hoch. Plain-HTTP ist nur für ein dediziertes Debug-Profil möglich.
* '''mTLS''' (Mutual TLS): erzwingt, dass jeder Client ein gültiges Client-Zertifikat vorlegt. Optional kann pro Zugang ein erwarteter Subject-DN hinterlegt werden.
* '''DNS-Cache:''' Host-zu-IP-Auflösungen für die Zugangs-Host-Prüfung werden 5 Minuten gecached.

==Protokoll==

Die Tabelle '''RESTSRV_PROTO''' enthält alle relevanten Ereignisse: erfolgreiche und abgelehnte Anfragen, TLS-/JWT-Fehler, Bindungs-Ereignisse, Skript-Fehler. Einträge sind nach Datum, Uhrzeit und Host (IP oder Account-Name) sortiert. Das Protokoll ist die erste Anlaufstelle bei Störungen. Jede Antwort trägt zudem eine Korrelations-ID (Response-Header ''X-Trace-Id''), die in den Protokoll-Einträgen wiederzufinden ist.

==Statistik==

Die Tabelle '''RESTSRV_STATS''' enthält eine Statistik aller bearbeiteten Anfragen mit Zugang, Endpunkt, Methode, HTTP-Status und Laufzeit in Millisekunden. Aufruf der Statistik:

* Aus der Endpunkt-Liste: F8 zeigt die Statistik des markierten Endpunkts.
* Aus der Zugänge-Liste: F8 zeigt die Statistik des markierten Zugangs.

==Konsole==

Wird der REST-Server nicht als Dienst, sondern interaktiv gestartet, erscheint eine farbige Konsole mit Live-Log. Die wichtigsten Befehle:

{| class="wikitable"
! Befehl !! Wirkung
|-
| ''show <n>'' || Zeigt die Details zum Debug-Eintrag ''#n'' (z.B. Request-Header, Response-Body), JSON wird farbig formatiert
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Einträge landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]] - API-Keys, JWT, CORS, Host-Beschränkung
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]] - Dateien ausliefern, Range/Resume, öffentliche Artefakte
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

Vorlage:Kostenpflichtige Module

2026-09-14T08:08:31Z

Rademacker:

<div style="float:right; clear:both; margin-left:2px; padding:0px; background:#FFFFFF; width:19em">
<div style="border:none;margin-top:0pt;padding:0pt;" id="navigation">

<div style="position:relative;top:-20pt;color:#000000;background:#ffffff; border: 3pt double #cfcfcf; padding: 5pt; margin: 0pt;margin-bottom:-20pt; z-index:1;border-top-right-radius:7pt;-moz-border-radius-topright:7pt;-webkit-border-top-right-radius:7pt;border-bottom-left-radius:7pt;-moz-border-radius-bottomleft:7pt;-webkit-border-bottom-left-radius:7pt;box-shadow: 3px 3px 4px #c0c0c0;-webkit-box-shadow: 3px 3px 4px #c0c0c0;-moz-box-shadow: 3px 3px 4px #c0c0c0;">[[Hauptseite|Wiki]] » [[Kostenpflichtige Module|Kostenpflichtige Module]]</div>
</div>

{{Vorlage:Textbox-Blau|1=Kostenpflichtige Module|2=
<small>
{{Vorlage:Klapptext|kopf='''Internet-Shop'''|inhalt=
* [[OBS/Stammdaten/Schnittstellen/Internet-Shop| OBS Schnittstelle Internet Shop]]
{{Vorlage:Klapptext|kopf='''Der modified ECommerce Shop'''|inhalt=
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop-xtcModified/FAQs|FAQs]]
*[[OBS/Internet-Shop/modified-eCommerce|Überblick zum modified ECommerce Shop]]
{{Vorlage:Klapptext|kopf=Shop-Menü|inhalt=
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/A Preise aktualisieren|A Preise aktualisieren]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/C Personen übertragen|C Personen übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/E Kategorien verwalten|E Kategorien verwalten]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/G Kataloge verwalten|G Kataloge verwalten]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop-xtcModified/I Merkliste übertragen|I Merkliste übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/K Varianten übertragen|K Varianten übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/L Artikelvarianten übertragen|L Artikelvarianten übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/M Referenzarten übertragen|M Referenzarten übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/N Lagerbestände verwalten|N Lagerbestände verwalten]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop#Bestellungen_einlesen|U Bestellungen einlesen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/V leere Passworte füllen|V leere Passworte füllen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/W Update-Informationen zurücksetzen|W Update-Informationen zurücksetzen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/Konfiguration/modified_eCommerce|X Konfiguration]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop#Protokoll|Z Protokoll]]
}}
{{Vorlage:Klapptext|kopf=Automatische Vorgänge|inhalt=
* [[OBS/Internet-Shop/modified-eCommerce/Scheduler/Bestellungen einlesen|Bestellungen einlesen]]
* [[OBS/Internet-Shop/modified-eCommerce/Scheduler/Verfügbarkeitsdateien erstellen|Verfügbarkeitsdateien erstellen]]
* [[OBS/Internet-Shop/modified-eCommerce/Scheduler/Verfügbarkeitsdateien hochladen|Verfügbarkeitsdateien hochladen]]
*[[OBS/Internet-Shop/modified-eCommerce/Scheduler/Änderungsautomatik|geänderte Artikel übertragen]]
*[[OBS/Internet-Shop/modified-eCommerce/Scheduler/Preise aktualisieren|Preise aktualisieren]]
*[[OBS/Internet-Shop/modified-eCommerce/Scheduler/Anlage Shopkategorien|Anlage der Shopkategorien auf Grundlage der OBS-Warengruppen]]
}}
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop-xtcModified/besondere Funktionen|Besondere Anpassungen im xtcModified Shop]]<br>
}}

{{Vorlage:Klapptext|kopf=[[Kostenpflichtige_Module/Internet-Shop/modified_eCommerce_2|modified eCommerce 2.0]]|inhalt=
*[[OBS/Internet-Shop/modified_eCommerce_2.0|Funktionen und FAQ]]
}}

{{Vorlage:Klapptext|kopf=[[OBS/Internet-Shop/ShopV4|Der Büroring-ShopV4]]|inhalt=
*[[OBS/Internet-Shop/ShopV4/FAQs|FAQs]]
{{Vorlage:Klapptext|kopf=Einrichtung|inhalt=
* [[OBS/Internet-Shop/ShopV4/1.1_Einstellungen_im_Shop|Einstellungen im Shop]]
* [[OBS/Internet-Shop/ShopV4/1.2_Einstellungen_in_OBS|Einstellungen in OBS]]
* [[OBS/Internet-Shop/ShopV4/Erste_Schritte|Erste Schritte]]
}}
* [[OBS/Internet-Shop/ShopV4/Shop-Menu|Shop-Menü]]
* [[OBS/Internet-Shop/ShopV4/Shop-Lieferanten|Shop-Lieferanten]]
* [[OBS/Internet-Shop/ShopV4/Import_von_Bestellungen|Import von Bestellungen]]
* [[OBS/Internet-Shop/ShopV4/Personen_/_Kundengruppen|Personen / Kundengruppe]]
{{Vorlage:Klapptext|kopf=Eigene Artikel|inhalt=
* [[OBS/Internet-Shop/ShopV4/6.1_Artikel_übertragen|Artikel übertragen]]
* [[OBS/Internet-Shop/ShopV4/6.2_Shop-Warengruppen|Shop-Warengruppen]]
}}
* [[OBS/Internet-Shop/ShopV4/Preislisten|Preislisten]]
* [[OBS/Internet-Shop/ShopV4/Katalogvorlagen|Katalogvorlagen]]
* [[OBS/Internet-Shop/ShopV4/Bestellvorlagen|Bestellvorlagen]]
* [[OBS/Internet-Shop/ShopV4/Sortiment|Sortiment]]
* [[OBS/Internet-Shop/ShopV4/Kostenstellen|Kostenstellen]]
* [[OBS/Internet-Shop/ShopV4/Personen-Einstellungen|Personen-Einstellungen]]
}}

{{Vorlage:Klapptext|kopf=[[Kostenpflichtige_Module/Internet-Shop/brShop24|brShop24]]|inhalt=
* [[Kostenpflichtige_Module/Internet-Shop/brShop24|Übersicht]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Einrichtung|Einrichtung]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24#Bekannte_Probleme|Bekannte Probleme]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24#H.C3.A4ufig_gestellte_Fragen_.28FAQ.29|Häufig gestellte Fragen (FAQ)]]
{{Vorlage:Klapptext|kopf=[[Kostenpflichtige_Module/Internet-Shop/brShop24|Einstellungen und Automatiken]]|inhalt=
* [[OBS/Stammdaten/Schnittstellen/Internet-Shop/Konfiguration|Konfiguration]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24#Zuordnungen|Zuordnungen/Datenverknüpfung OBS und Shop]]
* [[Kostenpflichtige_Module/Internet-Shop/Einrichtung/Automatiken|Automatiken einrichten]]
}}
{{Vorlage:Klapptext|kopf=[[Kostenpflichtige_Module/Internet-Shop/brShop24#Erkl.C3.A4rungen.2FFunktionen|Funktionen]]|inhalt=
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Kundengruppen_verwalten|Kundengruppen verwalten]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Personen_übertragen|Personen übertragen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Preise_übertragen|Preise übertragen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Eigene_Artikel_übertragen|Eigene Artikel übertragen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Shoppinglisten_übertragen|Shoppinglisten übertragen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Jobinformationen|Jobinformationen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Migration|Migration]]
* [[Kostenpflichtige Module/Internet-Shop/brShop24/PDF-Druck Artikellink|PDF-Druck Artikellink]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Definition_Sortiment|Definition Sortiment (individuelle Konfiguration)]]
}}
}}

* [[Kostenpflichtige Module/Internet-Shop/soCONNECT|so.CONNECT (Soennecken)]]

}}

{{Vorlage:Klapptext|kopf='''Preislisten'''|inhalt=
{{Vorlage:Klapptext|kopf=[[OBS/Kostenpflichtige_Module/Preislisten|Preislistenverwaltung]]|inhalt=
* [[OBS/Kostenpflichtige_Module/Preislisten/Preislisten-Artikel|Preislisten-Artikel]]
* [[OBS/Kostenpflichtige_Module/Preislisten/Preislistengruppen|Preislistengruppen]]
}}
* [[OBS/Preislisten/FAQ_Preislisten|FAQ Preislisten]]
* [[OBS/Häufig gestellte Fragen/Vorgehensweise für Preislisten ohne Server|Vorgehen für Preislisten ohne Server]]
* [[OBS/Häufig gestellte Fragen/Vorgehensweise mit Server/Client Installation für Preislisten|Vorgehen für Preislisten mit Server]]
{{Vorlage:Klapptext|kopf=[[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere Funktionen|F10 Weitere Funktionen]]|inhalt=
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Export_Import#A_Preisliste_nach_Excel|A Preisliste nach Excel]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Export_Import#B1_Excel_in_Preisliste|B1 Excel in Preisliste]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Export_Import#B2_freie_Excel_in_Preisliste|B2 freie Excel in Preisliste]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Export_Import#B3_Lieferanten-Preise_aus_CSV_in_Preisliste|B3 Lieferanten-Preise aus CSV in Preisliste]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/AutoPflege|C Automatische Vorgänge Preislisten]]
* [[OBS/Kostenpflichtige_Module/Preislisten/Formeln|D Formelverwaltung]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Angebot_Preisliste#F.C3.BCllen_einer_Preisliste_aus_Angebot|E1 Angebot nach Preisliste]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Angebot_Preisliste#Angebot_aus_Preisliste_generieren|E2 Preisliste nach Angebot]]
}}
{{Vorlage:Klapptext|kopf=[[OBS/Stammdaten/Artikel/Preislistenverwaltung/AutoPflege|Automatiken Kommandos]]|inhalt=
* [[OBS/Preislisten/Preislisten per Macro füllen|Preislisten per Macro füllen]]
* [[OBS/Preislisten/Preislisten per Macro kopieren|Preislisten per Macro kopieren]]
}}
}}

{{Vorlage:Klapptext|kopf='''ZUGFeRD'''|inhalt=
* [[OBS/Kostenpflichtige Module/ZUGFeRD|ZUGFeRD]]
* [[OBS/Kostenpflichtige Module/ZUGFeRD/Konfiguration|ZUGFeRD Konfiguration]]
}}
{{Vorlage:Klapptext|kopf='''Factoring'''|inhalt=
* [[OBS/Kostenpflichtige Module/Was ist Factoring?|Was ist Factoring?]]
* [[OBS/Kostenpflichtige Module/Factoring in OBS| Factoring in OBS]]
* [[OBS/Kostenpflichtige Module/Erstellen und Verwenden von Factoring Rechnungen|Erstellen und Verwenden von Factoring Rechnungen]]
* [[OBS/Kostenpflichtige Module/Auswertung und Übermittlung von Factoring Rechnungen|Auswertung und Übermittlung von Factoring Rechnungen]]
* [[OBS/Kostenpflichtige Module/Factoring Fibu|Factoring Fibu]]
}}
{{Vorlage:Klapptext|kopf='''UPS'''|inhalt=
* [[OBS/kostenpflichtige Module/UPS|UPS Modul]]
}}
{{Vorlage:Klapptext|kopf='''DHL'''|inhalt=
* [[OBS/kostenpflichtige Module/DHL|DHL Schnittstelle]]
}}
{{Vorlage:Klapptext|kopf='''IMS Professional'''|inhalt=
;
* [[OBS/kostenpflichtige Module/IMSPro|IMS-Professional]]

}}
{{Vorlage:Klapptext|kopf='''TAPI'''|inhalt=
* [[OBS/Kostenpflichtige Module/TAPI|TAPI]]
* [[OBS/Kostenpflichtige Module/TAPI Voraussetzungen|Voraussetzungen]]
* [[OBS/Kostenpflichtige Module/TAPI Konfiguration|Konfiguration]]
* [[OBS/Kostenpflichtige Module/TAPI Externe Telefonanbindungen|Externe Telefonanbindungen]]
}}
{{Vorlage:Klapptext|kopf='''SMS'''|inhalt=
* [[OBS/Kostenpflichtige Module/SMS|SMS]]
}}
{{Vorlage:Klapptext|kopf=[[OBS/Kostenpflichtige_Module/Fleet_Management|'''Fleet Management''']]|inhalt=
* [[OBS/Kostenpflichtige Module/Fleet Management/FMAudit|FMAudit]]
* [[FRMFMZENTRALE_MELDUNGEN|FMAudit Pro]]
* [[OBS/Kostenpflichtige Module/Fleet Management/UTAX E-mail|UTAX E-Mail]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/Brother_XML|Brother XML]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/KonicaMinolta_E-Mail|Konica Minolta E-Mail]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/docuFORM|docuFORM XML]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/KyoceraFleetServices|KFS XML]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/SimpleClicksXML|SimpleClicks XML]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/Brother_PPPB_xlsx|Brother PPPB Xlsx]]
}}
{{Vorlage:Klapptext|kopf='''Mehrlager-Verwaltung'''|inhalt=
* [[OBS/Kostenpflichtige Module/Mehrlager-Verwaltung|Mehrlager-Verwaltung]]
}}
{{Vorlage:Klapptext|kopf='''Mehrsprachen Modul'''|inhalt=
* [[OBS/Kostenpflichtige Module/Mehrsprachen Modul|Mehrsprachen Modul]]
}}
{{Vorlage:Klapptext|kopf='''Multilanguage Modul'''|inhalt=
* [[OBS/Kostenpflichtige Module/Multilanguage Modul|Multilanguage Modul]]
}}

{{Vorlage:Klapptext|kopf='''Einfache Produktionsnachverfolgung'''|inhalt=
* [[OBS/Einfache Produktionsnachverfolgung/Was ist|Was ist die Einfache Produktionsnachverfolgung]]
* [[OBS/Einfache Produktionsnachverfolgung/FRMEDITPRODMENGE|Scannen der Auftragspositionen]]
* [[OBS/Einfache Produktionsnachverfolgung/Sammellieferschein|Sammellieferschein]]
}}
{{Vorlage:Klapptext|kopf='''DMS - Dokumenten Management System'''|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS|DMS]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Konfiguration|Konfiguration]]
* [[OBS/Kostenpflichtige Module/DMS/Scannen von Dokumenten|Einscannen von Dokumenten im Stapelbetrieb]]
{{Vorlage:Klapptext|kopf=DMS Dokumente|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente|Liste]]
* [[OBS/Kostenpflichtige Module/DMS/Versionierung|Dokumentenversionierung]]
{{Vorlage:Klapptext|kopf=Tasten und Schaltflächen|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F2 Filter|F2 Filter]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F5 Markieren|F5 Mark]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Verknüpfung|F6 Verknü.]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F7 Suche|F7 Suche]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F8 Info|F8 Info]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F9 Gruppe|F9 Gruppe]]
{{Vorlage:Klapptext|kopf=F10 Weit.|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F10 Weitere Funktionen|F10 Weit.]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Stammdaten|DMS Stammdaten]]
{{Vorlage:Klapptext|kopf=E DMS Definitionen|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS Definitionen|Liste]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Definitionen Eingabemaske|Eingabemaske]]
}}
* [[OBS/Kostenpflichtige Module/DMS/QR Etiketten|M QR Etiketten drucken]]
}}
* [[OBS/Kostenpflichtige Module/DMS/DMS Viewer|Dokument]]
}}
* [[OBS/Kostenpflichtige Module/DMS/DMS Eingabemaske|Eingabemaske]]
}}
}}

{{Vorlage:Klapptext|kopf='''QR Zeiterfassung'''|inhalt=
* [[OBS/Kostenpflichtige Module/QR Zeiterfassung|QR Zeiterfassung]]
* [[OBS/Kostenpflichtige Module/QR Einrichtung Checkliste|QR Einrichtung Checkliste]]
}}

{{Vorlage:Klapptext|kopf='''EVA Marketing Tool'''|inhalt=
* [[OBS/EVA]]
}}

{{Vorlage:Klapptext|kopf='''Technikersteuerung'''|inhalt=
* [[OBS/Kostenpflichtige Module/Technikersteuerung/Ziel der Technikersteuerung|Ziel der Technikersteuerung]]
* [[OBS/Kostenpflichtige Module/Technikersteuerung/Konfiguration|Konfiguration]]
* [[OBS/Kostenpflichtige Module/Technikersteuerung/Terminvorschläge erstellen|Terminvorschläge für Techniker erstellen]]
* [[OBS/Kostenpflichtige Module/Technikersteuerung/Liste|Liste]]
** [[OBS/Kostenpflichtige Module/Technikersteuerung/Definition Terminvorschlagslisten|Definition Terminvorschlagslisten/T-Def]]
** [[OBS/Kostenpflichtige Module/Technikersteuerung/Terminvorschläge bearbeiten|Terminvorschläge für Techniker bearbeiten]]
** [[OBS/Kostenpflichtige Module/Technikersteuerung/Terminvorschlagsliste aktualisieren|Terminvorschlagsliste akt./T-Liste]]
}}

{{Vorlage:Klapptext|kopf='''Termin-Projekte'''|inhalt=
* [[OBS/Kostenpflichtige Module/Termin-Projekte|Termin-Projekte]]
}}

{{Vorlage:Klapptext|kopf='''Edifact-Schnittstelle'''|inhalt=
* [[OBS/Kostenpflichtige Module/Edifact|Edifact Schnittstelle]]
}}

{{Vorlage:Klapptext|kopf='''Backup Überwachung Email'''|inhalt=
* [[OBS/Kostenpflichtige Module/Backup Überwachung Email|Backup Überwachung Email]]
}}

{{Vorlage:Klapptext|kopf='''Anlagenbuchhaltung'''|inhalt=
* [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung|Anlagenbuchhaltung]]
** [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Auswertungen|Auswertungsdrucke]]
** [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Anlagengüter|Anlagegüterübersicht]]
** [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Abschreibungsarten|Abschreibungsarten]]
* [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Anlagekonten|Anlagekonten]]
* [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Bewegung|Anlagebewegungen]]
* [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Anlagenstapel|Anlagenstapel]]
}}

{{Vorlage:Klapptext|kopf='''OBS Geo Daten'''|inhalt=
* [[OBS/Kostenpflichtige Module/OBS Geo Daten|OBS Geo Daten]]
}}

{{Vorlage:Klapptext|kopf='''DeliSprint / DPD'''|inhalt=
* [[OBS/Kostenpflichtige_Module/Delisprint|DeliSprint / DPD]]
}}

{{Vorlage:Klapptext|kopf='''Filialen'''|inhalt=
* [[OBS/Kostenpflichtige Module/Filialen|Filialen]]
}}

{{Vorlage:Klapptext|kopf='''Auto-Waagen'''|inhalt=
* [[OBS/Kostenpflichtige Module/Auto-Waagen|Auto-Waagen]]
* [[OBS/Kostenpflichtige Module/Auto-Waagen/Installation|Installation]]
* [[OBS/Kostenpflichtige Module/Auto-Waagen/Liste|Liste]]
* [[OBS/Kostenpflichtige Module/Auto-Waagen/Eingabemaske|Eingabemaske]]
* [[OBS/Kostenpflichtige Module/Auto-Waagen/Waage.INI|Waage.INI]]
}}

{{Vorlage:Klapptext|kopf='''Cashback'''|inhalt=
* [[OBS/Kostenpflichtige Module/Cashback|Cashback]]
}}
{{Vorlage:Klapptext|kopf='''Moebelschnittstelle'''|inhalt=
*[[OBS/Kostenpflichtige Module/Moebelschnittstelle|Moebelschnittstelle]]
}}
{{Vorlage:Klapptext|kopf='''Tourenplanung'''|inhalt=
{{Vorlage:Klapptext|kopf=[[OBS/Kostenpflichtige Module/Tourenplanung|Tourenplanung]]|inhalt=
*[[OBS/Kostenpflichtige Module/Tourenplanung/TourVG|Vorgänge]]
*[[OBS/Kostenpflichtige Module/Tourenplanung/TourTouren|Touren]]
*[[OBS/Kostenpflichtige Module/Tourenplanung/TourTourPos|Positionen]]
}}
*[[OBS/Kostenpflichtige Module/Tourenplanung/Stammdaten|Stammdaten]]
*[[OBS/Kostenpflichtige Module/Tourenplanung/Einrichtung|Einrichtung]]
}}
{{Vorlage:Klapptext|kopf='''Dokumenten Manager'''|inhalt=
*[[OBS/Kostenpflichtige_Module/Dokumenten_Manager|Dokumenten Manager]]
}}
{{Vorlage:Klapptext|kopf='''DocuWare-Schnittstelle'''|inhalt=
*[[OBS/Kostenpflichtige_Module/DocuWare|DocuWare-Schnittstelle]]
}}
{{Vorlage:Klapptext|kopf='''OFML-Kalkulation'''|inhalt=
*[[OBS/Kostenpflichtige_Module/OFML-Kalkulation|OFML-Kalkulation]]
}}
{{Vorlage:Klapptext|kopf='''Pascom'''|inhalt=
*[[OBS/Kostenpflichtige_Module/Pascom|Pascom]]
*[[OBS/Kostenpflichtige_Module/Pascom_Einrichtung|Einrichtung]]
}}
{{Vorlage:Klapptext|kopf='''Versicherungsschaden'''|inhalt=
*[[OBS/Kostenpflichtige_Module/Versicherungsschaden|Versicherungsschaden]]
*[[OBS/Kostenpflichtige_Module/Energienachweise|Energienachweise]]
}}
{{Vorlage:Klapptext|kopf='''Gutschriftsanzeigen'''|inhalt=
* [[OBS/Kostenpflichtige Module/Gutschriftsanzeigen|Gutschriftsanzeigen]]
}}
{{Vorlage:Klapptext|kopf='''OCPP Ladestationen'''|inhalt=
* [[OBS/Kostenpflichtige Module/OCPP_Ladestationen|OCPP Wallboxen Abrechnung (Ladesäulen)]]
* [[OBS/Kostenpflichtige Module/SteVe|SteVe]]
}}
{{Vorlage:Klapptext|kopf='''Kameraverwaltung'''|inhalt=
* [[OBS/Kostenpflichtige Module/Kameraverwaltung|Kameraverwaltung]]
}}
{{Vorlage:Klapptext|kopf='''DataInOut'''|inhalt=
* [[OBS/Kostenpflichtige Module/DataInOut|DataInOut]]
}}
{{Vorlage:Klapptext|kopf='''REST-Schnittstelle'''|inhalt=
* [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]]
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Skripting]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
{{Vorlage:Klapptext|kopf='''Beispiele'''|inhalt=
*[[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|PHP-Abruf von Steuerungsdaten]]
*[[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Zeiterfassung]]
*[[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Externes Ticketsystem]]
*[[OBS/Kostenpflichtige_Module/RESTServer/Beispiel4|Pfad-Parameter]]
*[[OBS/Kostenpflichtige_Module/RESTServer/Beispiel5|Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
*[[OBS/Kostenpflichtige_Module/RESTServer/Beispiel6|Datei-Upload und Ablage im DMS]]
}}
}}

{{Vorlage:Klapptext|kopf='''Sammelverträge'''|inhalt=
* [[OBS/Kostenpflichtige Module/Sammelvertrag|Sammelvertrag]]
* [[OBS/Kostenpflichtige Module/Sammelvertrag/Container|Container-Stammdaten]]
}}

{{Vorlage:Klapptext|kopf='''Craftboxx'''|inhalt=
* [[OBS/Kostenpflichtige Module/Craftboxx|Craftboxx]]
* [[OBS/Kostenpflichtige Module/CraftboxxAPI|Craftboxx API Dokumentation]]
}}

{{Vorlage:Klapptext|kopf='''OpenMasterData / IDS'''|inhalt=
* [[OBS/Kostenpflichtige Module/OpenMasterData|OpenMasterData]]
* [[BS/Kostenpflichtige Module/IDSConnect|IDSConnect]]
}}

{{Vorlage:Klapptext|kopf='''Sammelpositionen'''|inhalt=
* [[OBS/Kostenpflichtige Module/Sammelpositionen|Sammelpositionen]]
}}

{{Vorlage:Klapptext|kopf='''KI-Mining'''|inhalt=
* [[OBS/Kostenpflichtige Module/KI-Mining|KI-Mining]]
{{Vorlage:Klapptext|kopf=KI-Mining Apps|inhalt=
* [[OBS/Kostenpflichtige Module/KI-Mining/Auftragsmonitor|Auftragsmonitor]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Lageroptimierung|Lageroptimierung]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Kundenklassifizierung|Kundenklassifizierung]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Cross-Selling|Cross-Selling]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Vertriebs-ToDos|Vertriebs-ToDos]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Vertriebs-ToDos pro|Vertriebs-ToDos pro]]
* [[OBS/Kostenpflichtige Module/KI-Mining/MPS-ToDos pro|MPS-ToDos pro]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Vertriebs-Wirkungsmonitor|Vertriebs-Wirkungsmonitor]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Führungs-Dashboard|Führungs-Dashboard]]
}}
}}

</small>
}}

</div>

<noinclude>
----
</noinclude>

<noinclude>

Folgender Code muss in die jeweils gewünschte Seite hinzugefügt werden:
<nowiki>{{Kostenpflichtige Module}}</nowiki>
[[Kategorie:Templates/Navigationen]]
</noinclude>
[[Kategorie:OBS/Module]]

OBS/Kostenpflichtige Module/RESTServer/Datei-Download

2026-09-14T08:07:57Z

Rademacker: Die Seite wurde neu angelegt: „{{Kostenpflichtige Module}} = Datei-Download = Ein Endpunkt kann statt eines JSON-Körpers eine '''Datei''' ausliefern - PDF, CSV, Bilder, eine APK. Das Skript entscheidet das mit einem einzigen Aufruf, alles Weitere macht der Server: Content-Type, Dateiname, Bereichsanfragen und, bei temporären Dateien, das Aufräumen. Anders als beim Datei-Upload braucht es dafür '''keine Freischaltung''' am E…“

OBS/Kostenpflichtige Module/RESTServer/Scripting

2026-09-14T08:07:39Z

Rademacker:

{{Kostenpflichtige Module}}

=Anleitung für Endpunkt-Skripte=

Jede Anfrage an einen Endpunkt wird nach erfolgreicher Authentifizierung und Autorisierung an das hinterlegte Skript weitergegeben. Das Skript ist in Object Pascal geschrieben und greift auf die OBS-Bibliothek (DB-Zugriff, Hilfsfunktionen) zu.

==Sicherheitshinweise==

{{Hinweis|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Übergabeparameter dürfen niemals ungeprüft in SQL-Anweisungen eingebaut werden. Werte immer über ''DB_SQLVal'' bzw. Parameter-Bindings absichern, Eingabewerte gegen Whitelists prüfen.}}

* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
* Nur das zurückgeben, was der Konsument wirklich braucht - keine internen IDs, keine Sys-Felder, keine Passwörter.
* Bei Fehlern keine internen Details an den Konsumenten zurückgeben; stattdessen schreibt der Server ohnehin Detail-Einträge in '''RESTSRV_PROTO'''.

==Methoden-Signatur==

Pro HTTP-Methode wird im Skript eine gleichnamige '''Prozedur''' implementiert. Der Server ruft genau die Prozedur auf, die zur Methode des eingehenden Requests passt.

procedure Get (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Patch (oReader: TxRestReader; oWriter: TxRestWriter);

Zwei Handles, kein Rückgabewert: '''oReader''' ist die Anfrage, '''oWriter''' die
Antwort. Beide erzeugt der Server, beide gehören ihm - im Skript wird nichts
angelegt und nichts freigegeben.

{{Achtung|'''DELETE hat keine Skript-Methode.''' <code>Delete</code> ist in der
Skriptsprache eine Standardprozedur (Löschen aus einer Zeichenkette); eine eigene
Prozedur dieses Namens lässt sich nicht übersetzen, und der Fehler nennt nur die
Zeile der Deklaration. Wer einen DELETE-Endpunkt braucht, legt die Methode unter
einem anderen Verb ab oder trennt sie in ein eigenes Skript.}}

Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
Not Allowed''' (<code>METHOD_NOT_ALLOWED</code>) und nennt im Header
<code>Allow</code> die Verben, die dieses Skript tatsächlich anbietet - die Liste
stammt aus dem kompilierten Skript und kann deshalb nicht veralten:

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT

Ein im Vertrag zugesagtes Verb braucht also seine Prozedur. Fehlt sie, ist das an
der Antwort sofort zu erkennen und '''kein''' Serverfehler.

==Die Anfrage lesen: oReader==

''oReader'' ist der einzige Zugang zur Anfrage - Query, Header, Formularfelder,
Pfadwerte, Token-Claims und Körper. Alles davon sind '''Zeichenketten''' oder
werden über einen typisierten Leser geholt.

{| class="wikitable"
! Aufruf !! Was er liefert
|-
| <code>oReader.Param('kundennr')</code> || Query-Parameter, POST-Parameter (form-urlencoded) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet
|-
| <code>oReader.Path('uid')</code> || Wert eines Platzhalters aus dem Pfad-Template
|-
| <code>oReader.Form('bemerkung')</code> || Formularfeld einer <code>multipart/form-data</code>-Übertragung
|-
| <code>oReader.Claim('tenant')</code> || Custom-Claim des vorgelegten Tokens
|-
| <code>oReader.Subject()</code> || Subject des Tokens (''sub''-Claim)
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests
|-
| <code>oReader.Offset()</code> || UTC-Offset des Servers, z.B. ''+02:00''
|-
| <code>oReader.HasBody()</code> || Wurde überhaupt ein JSON-Körper gesendet?
|}

Filterung durch den Server:

* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
* Werte, die von aussen kommen, können die reservierten Namen nicht besetzen.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.

Zugriff im Skript:

cKundenNr := oReader.Param('kundennr');
if (not Empty(cKundenNr)) then begin
// ...
end;

===Der Körper: Zugriff über Pfade===

Den JSON-Körper liest ''oReader'' über '''Pfade'''. Es gibt keine Unterobjekte im
Skript, keinen Cast, kein ''.Items[i]'' - und damit auch keine Lebensdauer, um die
sich jemand kümmern müsste.

{| class="wikitable"
! Aufruf !! Bedeutung
|-
| <code>oReader.Str('betreff', cWert)</code> || Liest den Wert. '''Rückgabe Boolean''': war das Feld da? Fehlt es, bleibt die Variable unverändert
|-
| <code>oReader.Int('menge', nWert)</code> || dito, Ganzzahl
|-
| <code>oReader.Num('preis', nWert)</code> || dito, Kommazahl. '''Der Dezimalpunkt aus JSON wird richtig gelesen''' - kein ''StrTran'' mehr
|-
| <code>oReader.Bool('aktiv', lWert)</code> || dito, Boolean
|-
| <code>oReader.NumDef('rabatt', nWert, 0)</code> || wie ''Num'', mit Vorgabewert
|-
| <code>oReader.Has('feld')</code> || Ist das Feld vorhanden? (auch bei ''null'')
|-
| <code>oReader.Count('zeiten')</code> || Anzahl Einträge einer Liste, 0 wenn keine Liste
|-
| <code>oReader.IsArr('zeiten')</code> / <code>IsObj('zeiten[0]')</code> || Gestalt prüfen
|-
| <code>oReader.Keys()</code> || Alle Feldnamen der obersten Ebene, in Kommas eingefasst
|}

'''Verschachtelung steht im Pfad''' - Punkt für Felder, eckige Klammern für Listen:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cVon : string;
nAnz : Integer;
nI : Integer;
begin
nAnz := oReader.Count('zeiten');
for nI := 0 to nAnz - 1 do begin
if (oReader.Str('zeiten[' + IntToStr(nI) + '].von', cVon)) then begin
// ... cVon verarbeiten ...
end;
end;
end;
</syntaxhighlight>

{{Hinweis|'''Der Rückgabewert unterscheidet „nicht gesendet" von „leer
gesendet".''' <code>oReader.Str('feld', cWert)</code> liefert bei
<code>"feld": null</code> ''true'' mit leerem Wert und bei fehlendem Feld
''false''. Genau diese Unterscheidung braucht ein PATCH-artiger Aufruf: „Feld
löschen" und „Feld nicht anfassen" sehen sonst gleich aus.}}

Ist gar kein Körper gesendet worden, liefert jeder Leser ''false'' und
''HasBody()'' ist ''false''. Maximale Body-Grösse: 10 MB.

===Werte des Servers===

Bei aktiver JWT-Authentifizierung stehen die Token-Claims über den Reader zur
Verfügung. Sie tragen intern weiterhin die Namen mit Präfix '''_OBS_''' - im
Skript werden sie aber über die Zugriffe der Tabelle oben gelesen und nicht mehr
über den Namen:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_JWT_ID')</code> || JWT-Id (''jti''-Claim) - typisch die User-Id. '''Muss nicht eindeutig sein''': die Sitzung führt der Server über eigene Kennungen (siehe unten)
|-
| <code>oReader.Subject()</code> || Subject (''sub''-Claim) - typisch Benutzername
|-
| <code>oReader.Param('_OBS_JWT_AUDIENCE')</code> || Audience (''aud''-Claim) - typisch Mandant / Rolle
|-
| <code>oReader.Claim('tenant')</code> || Beliebiger Custom-Claim des Tokens, hier ''tenant''; im Folge-Skript lesbar
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}

Unabhängig von JWT stehen ausserdem immer zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_SERVER_TIME')</code> || Aktuelle Serverzeit als ISO-8601 '''mit UTC-Offset''' (z.B. ''2026-08-17T09:12:33+02:00''). Nützlich, um Datumswerte in derselben Zeitzone auszuliefern, in der der Server arbeitet, und damit ein Client seinen Uhren-Versatz bestimmen kann
|-
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+02:00''. Er geht in die Zeitfunktionen (siehe [[#Zeitangaben auf der Leitung|Zeitangaben]])
|-
| <code>oReader.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden (''JWT-Exp'' × 60). Damit kann ein Konfigurations-Endpunkt denselben Wert ausliefern, den der Token wirklich hat
|}

Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.

Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
''oReader.Claim('sid')'' und ''oReader.Claim('rid')'':

{| class="wikitable"
! Claim !! Inhalt
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
|}

Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Skripts gesetzt - ein Skript kann sie also auch mit einem eigenen Claim ''sid''
nicht überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.

===Pfad-Parameter===

Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte über ''oReader.Path'' bereit:

{| class="wikitable"
! Template !! Zugriff im Skript
|-
| <code>/orders/{uid}</code> || <code>oReader.Path('uid')</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>oReader.Path('uid')</code>, <code>oReader.Path('code')</code>
|}

Diese Werte kommen aus dem Routing und sind durch den Client nicht fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].

===Datei-Uploads===

Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), nimmt der Server
hochgeladene Dateien entgegen, legt sie in einem temporären Verzeichnis ab und
übergibt dem Skript Pfad, Originalname und Content-Type über den Reader. Das
Skript entscheidet selbst über die weitere Verarbeitung (z.B. DMS-Ablage). Der
Body wird in diesem Fall '''nicht''' als JSON geparst - ''oReader.HasBody()'' ist
''false''. Es gilt nicht das JSON-Body-Limit (10 MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25 MB;
Überschreitung -> 413).

'''Wie die Datei übertragen wurde, spielt für das Skript keine Rolle.''' Beide
Wege - <code>multipart/form-data</code> und der resumable
<code>Content-Range</code>-Upload - liefern dieselben vier Werte. Das
Übertragungsprotokoll samt Header, Statuscodes und Resume-Verhalten steht in
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]:

{| class="wikitable"
! Aufruf !! Inhalt
|-
| <code>oReader.UploadPath()</code> || Vollständiger Pfad zur temporären Datei auf dem Server
|-
| <code>oReader.UploadName()</code> || Originaldateiname
|-
| <code>oReader.UploadType()</code> || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt), kleingeschrieben
|-
| <code>oReader.UploadSha()</code> || SHA-256 der '''gespeicherten''' Datei, hex in Kleinbuchstaben. Damit lässt sich eine vom Client mitgesendete Prüfsumme vergleichen - erst dieser Vergleich macht aus ihr eine Zusicherung
|}

Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''UploadPath()'' und ''UploadName()'' gefüllt
sind, sobald es läuft.

{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}

Zusatzangaben, die im selben Aufruf mitkommen, liest das Skript mit
<code>oReader.Form('<name>')</code> - bei <code>multipart/form-data</code> sind
das die Partien ohne <code>filename=</code>. Ein vollständiges Beispiel zeigt
[[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].

==Die Antwort schreiben: oWriter==

Der Writer schreibt '''sequentiell''': jeder Aufruf hängt ein Feld an, an der
Stelle, an der er steht. Die äussere Klammer der Antwort setzt der Server. Wird
nichts geschrieben, antwortet er mit ''{}''. Content-Type ist
''application/json; charset=utf-8'', der Status 200, sofern das Skript nichts
anderes setzt.

Einfaches Beispiel:

<syntaxhighlight lang="pascal" line>
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
oWriter.Str('wert_string', '123');
oWriter.Int('wert_int' , 456);
end;
</syntaxhighlight>

{| class="wikitable"
! Aufruf !! Ergebnis
|-
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert
|-
| <code>oWriter.StrN('name', cWert)</code> || wie ''Str'', aber '''null''' statt einer leeren Zeichenkette
|-
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl
|-
| <code>oWriter.Num('preis', nWert, 2)</code> || Kommazahl mit fester Stellenzahl. '''Immer mit Dezimalpunkt''', unabhängig von der Locale des Servers
|-
| <code>oWriter.Bool('aktiv', lWert)</code> || ''true'' / ''false''
|-
| <code>oWriter.Null('lat')</code> || ausdrücklich ''null''
|-
| <code>oWriter.ObjBegin('kunde')</code> … <code>oWriter.ObjEnd</code> || Unterobjekt
|-
| <code>oWriter.ArrBegin('dateien')</code> … <code>oWriter.ArrEnd</code> || Liste
|-
| <code>oWriter.RootArr()</code> || Die '''Wurzel''' ist eine Liste statt eines Objekts. Muss vor dem ersten Feld stehen; ein ''ArrEnd'' gibt es dazu nicht
|-
| <code>oWriter.Raw('meta', cJson')</code> || Fertiges JSON-Fragment einbetten. Siehe unten
|}

'''In einer Liste hat ein Eintrag keinen Namen''' - der leere Feldname ist genau
das:

<syntaxhighlight lang="pascal" line>
oWriter.ArrBegin('dateien');
while (not q.EoF) do begin
oWriter.ObjBegin('');
oWriter.Str ('uid' , q.A2C('f_uid'));
oWriter.Int ('bytes' , q.A2I('f_bytes'));
oWriter.StrN('kategorie', AllTrim(q.A2C('f_kat'))); // null wenn leer
oWriter.ObjEnd;
q.Next();
end;
oWriter.ArrEnd;
</syntaxhighlight>

Ein Name in einer Liste und ein fehlender Name in einem Objekt sind beides
'''Strukturfehler'''. Der Server antwortet dann mit '''500''' und nennt die
Stelle im Protokoll - er liefert kein halbes JSON aus. Dasselbe gilt für einen
Stapel, der am Ende der Methode noch offen ist.

{{Hinweis|'''Ein Helfer bekommt den Writer als Parameter''' und schreibt an der
Stelle hinein, an der er aufgerufen wird - er gibt kein Fragment zurück. Damit
steht die Reihenfolge der Antwort im Code und nicht im Zusammenbau:

<code>procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);</code>}}

'''Raw ist der Notausgang und prüft.''' Er parst das Fragment und bettet den
'''Originaltext''' ein; ungültiges JSON gibt einen Serverfehler, der das Feld
nennt. Gebraucht wird er für ein gespeichertes, '''signiertes''' Dokument:
Parsen und Neuserialisieren würde die signierte Feldreihenfolge zerstören.

===Zeitangaben auf der Leitung===

Zeitstempel gehen als '''ISO-8601 mit Offset''' über die Leitung. Die Wandlung
gehört nicht ins Skript - dort saß der Fehler „zwei Stunden zu früh" an drei
Stellen gleichzeitig:

{| class="wikitable"
! Aufruf !! Zweck
|-
| <code>RestIsoFromDate(dWert, cOffset)</code> || OBS-Zeitpunkt -> ''2026-09-09T14:12:00+02:00''. Leerer String bei leerem Datum
|-
| <code>RestDateFromIso(cWert, cOffset)</code> || ISO-Zeichenkette -> OBS-Zeitpunkt in '''Ortszeit des Servers'''
|-
| <code>oReader.Offset()</code> || Der Offset, der in beide hineingeht
|-
| <code>RestOffsetToMinutes(cOffset)</code> || Offset in Minuten, für eigene Rechnungen
|}

==Antwort steuern: Statuscode, Header, traceId==

Statuscode, Header und das Sperren einer Sitzung laufen über eigene Aufrufe des
Writers, '''nicht''' über Felder im Körper.

{| class="wikitable"
! Aufruf !! Wirkung
|-
| <code>oWriter.Status(201)</code> || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200
|-
| <code>oWriter.Header('ETag', '7')</code> || Beliebiger Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen und Werten werden entfernt (Schutz vor Header-Injection)
|-
| <code>oWriter.NoBody()</code> || Kein Körper - für '''204'''
|-
| <code>oWriter.JwtRevoke('session')</code> || Sperrt die Sitzung des vorgelegten Tokens (''session'') oder alle Sitzungen des Subjects (''all''). Damit wird ein Endpunkt zum Logout, ohne eigene Verwaltung. Scheitert das Sperren, antwortet der Server mit '''503''' statt mit der Antwort des Skripts - siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Abschnitt Abmelden
|-
| <code>oWriter.Error(422, 'VALIDATION_FAILED', 'Feld „menge" fehlt')</code> || Fertige Fehlerantwort in der Form des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]]
|-
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer? Für einen Verteiler, der danach noch etwas anhängen will
|-
| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> || Statt eines JSON-Körpers eine '''Datei''' ausliefern. Die Datei bleibt liegen, der Download ist wiederaufsetzbar. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
|-
| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> || Wie <code>SendFile</code>, aber die Datei wird nach dem Senden '''gelöscht''' und der Download ist nicht wiederaufsetzbar - für Ergebnisse, die je Abruf entstehen (CSV-Export, Report)
|}

Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oReader.TraceId()'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

===Beispiel: Anlegen mit 201, Location und ETag===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueUid: string;
begin
// ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...

oWriter.Str('uid', cNeueUid);
oWriter.Status(201);
oWriter.Header('Location', '/v1/orders/' + cNeueUid);
oWriter.Header('ETag' , '1');
end;
</syntaxhighlight>

===Beispiel: Strukturierter Fehler mit Statuscode und traceId===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var nMenge: Integer;
begin
if (not oReader.Int('menge', nMenge)) then begin
// Statuscode, code, message, uid und traceId in EINEM Aufruf - dieselbe
// Huelle, die auch die Server-eigenen Fehler tragen.
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

===Beispiel: Optimistic Concurrency (ETag / If-Match)===

Mit Statuscode, Headern und dem lesbaren Header ''If-Match'' führt das Skript je Datensatz einen Versionszähler und lehnt veraltete Schreibzugriffe mit 409 ab:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var nAktuell: Integer;
nIfMatch: Integer;
begin
nAktuell := AuftragVersion(oReader.Path('uid'));
nIfMatch := iVal(oReader.Param('if-match'));

if (nIfMatch <> nAktuell) then begin
// Der ETag gehoert AUCH an die Ablehnung - sonst kennt der Client den
// gueltigen Wert nicht und sein naechster Versuch scheitert wieder.
oWriter.Header('ETag', xStr(nAktuell));
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geaendert');
exit;
end;

// ... speichern, Version hochzählen ...
oWriter.Header('ETag', xStr(nAktuell + 1));
end;
</syntaxhighlight>

==Idempotenz - was das Skript beachten muss==

Sendet ein Konsument bei ''POST''/''PUT''/''PATCH''/''DELETE'' den Header
<code>Idempotency-Key</code>, fängt der '''Server''' doppelte Sendungen ab. Das
Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine
Prüfung am Anfang der Methode.

Was das Skript wissen muss:

{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
|-
| '''2xx''' || Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
|-
| '''5xx''' oder Exception || Der Schlüssel bleibt belegt, der Fall wird protokolliert. Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist
|}

Daraus folgen zwei Regeln für Endpunkt-Skripte:

* '''Fachliche Ablehnungen als 4xx melden''' (422, 409, 404), nicht als 2xx mit Fehlertext im Body. Sonst wird die Ablehnung gespeichert und der Konsument bekommt sie bei jedem weiteren Versuch erneut - auch nachdem er den Fehler behoben hat.
* '''Die Antwort muss vollständig sein.''' Was zurückgegeben wird, wird eingefroren. Ein Feld, das erst der zweite Aufruf ergänzen würde, kommt beim Konsumenten nie an.

Der vollständige Ablauf und die Statuscodes stehen unter
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==JWT-Authentifizierungs-Skript==

Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
cPass: string;
begin
// Eingangsdaten lesen
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

// Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
if (PasswortPasst(cUser, cPass)) then begin
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_AUDIENCE', 'mandant1');
end else begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Login fehlgeschlagen');
end;
end;
</syntaxhighlight>

{{Hinweis|'''Im Anmeldeskript bleiben die _OBS_JWT_*-Felder Felder der
Antwort''' - anders als Status und Header, die zu Aufrufen des Writers geworden
sind. Der Grund: die Token-Ausstellung liest sie aus dem fertigen Körper, und
genau dort erwartet sie sie. Geschrieben werden sie deshalb wie jedes andere
Feld, nur eben mit dem Writer.}}

Rückgabewerte:

{| class="wikitable"
! status !! Bedeutung
|-
| 1 || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
|-
| 9 || Misserfolg, der Server antwortet mit '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
|}

{{Hinweis|Der Text aus ''error'' geht bei ''status'' = 9 '''an den Konsumenten'''
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Endanwender verständlich sein und keine internen Details verraten.}}

Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
„Passwort falsch" erscheinen.

Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.

===Aufbau der Token-Antwort===

Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
Feldern, die das Skript zurückgibt''':

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...",
"accessToken": "eyJ...",
"refreshToken":"eyJ...",
"expiresIn": 28800,
"serverTime": "2026-08-17T09:12:33+02:00"}

{| class="wikitable"
! Feld !! Herkunft
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
|-
| serverTime || Serverzeit ISO-8601 mit Offset
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
|}

Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.

===Custom-Claims, serverTime und Refresh===

Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:

{| class="wikitable"
! RÜckgabefeld !! Bedeutung
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als <code>oReader.Claim('<name>')</code>.
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
|}

Jedes Token trägt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh'') sowie die Sitzungskennungen ''sid'' und ''rid'' des Servers. Die Antwort enthält bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusätzlich ''refreshToken'':

{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}

{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''oReader.Claim(…)''), nie aus Body oder Query.}}

====Refresh-Methode====

Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
(Signatur, Ablauf, ''token_use=refresh'') und in der Sitzung '''entwertet'''.
Einmalgebrauch, Rotation und Sperrliste sind damit Sache des Servers. Das Skript
liefert nur noch die aktuellen Claims - genau das ist der Sinn des Aufrufs: eine
zwischenzeitlich geänderte Rolle oder ein gewechselter Mandant wirken spätestens
mit der nächsten Erneuerung.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal - einmal im Skript, einmal im
Server - und riskiert, dass beide Seiten unterschiedlicher Meinung sind. Der
Server sieht die Skript-Tabelle nicht, und das Skript sieht die Sitzung nicht.}}

Ein bereits benutztes Refresh-Token wird mit '''401''' abgelehnt. Erfolgt die
erneute Vorlage innerhalb von 60 Sekunden, bleibt die Sitzung bestehen (paralleler
Refresh einer App); danach gilt sie als Wiedervorlage und die '''gesamte Sitzung
wird gesperrt'''. Details in [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

Das alte Refresh-jti steht weiterhin als ''oReader.Param('_OBS_JWT_ID')'' bereit,
falls das Skript es für eigene Protokollierung braucht.

<syntaxhighlight lang="pascal" line>
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
begin
cUser := oReader.Subject();

// Der Server hat das vorgelegte Refresh-Token bereits geprueft und
// entwertet. Hier wird nur entschieden, ob der Benutzer die Sitzung
// fortsetzen darf - und mit welchen Rechten.
if (not BenutzerAktiv(cUser)) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
exit;
end;

// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das neue Refresh-Token aus
end;
</syntaxhighlight>

===Abmelden (Logout)===

'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Phase 4.

Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
'''gewöhnlichen Endpunkt''' und setzt dort ''_OBS_JWT_REVOKE''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
GeraeteRegistrierungLoeschen(oReader.Subject());

// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('session');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
abgemeldet, während sein Token weiterläuft.

==Fehlerbehandlung im Skript==

Tritt im Skript eine Exception auf oder schlägt die Syntax-Prüfung fehl, antwortet der Server mit 500 ''Interner Fehler'' und protokolliert die Detail-Meldung in '''RESTSRV_PROTO''' (mit Skript-Fehlertext). Der Konsument sieht keine internen Details.

Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Für einen spezifischen Fehler an den Konsumenten gibt es '''einen''' Aufruf. Er
baut dieselbe Hülle, die auch die Server-eigenen Fehler tragen - Statuscode,
''code'', ''message'', ''uid'' und ''traceId'' -, sodass beide Wege nicht
auseinanderlaufen können:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
if (Empty(oReader.Param('kundennr'))) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

{{Hinweis|'''Error verwirft einen schon begonnenen Körper''' und setzt seinen
eigenen. Ein Skript darf also getrost Felder schreiben und danach noch
abbrechen - was der Client sieht, ist die Fehlerantwort. Nur ein '''offener
Stapel''' (ein ''ObjBegin'' ohne ''ObjEnd'') bleibt auch dann ein Strukturfehler.}}

{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
Body auszuwerten - und nur so gibt der Server einen belegten
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}

===Ändern: qSqlInit statt qSqlRead===

Zum '''Ändern''' eines vorhandenen Satzes wird ebenfalls <code>qSqlInit</code>
benutzt - der Satz wird über <code>sys_uid</code> adressiert:

<syntaxhighlight lang="pascal" line>
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cSysUid); // Schreib-Index auf den Originalsatz
q.qSet('ti_status', '9');
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln, siehe unten
end;
qSqlFree(q);
</syntaxhighlight>

<code>qSqlRead</code> ist dafür die falsche Wahl, aus zwei Gründen:

* Es liest den '''kompletten Altsatz''' ein - ein zusätzlicher Lesezugriff, der Zeit kostet.
* Es schreibt anschliessend nur die '''Änderungen'''. Ist der neue Wert gleich dem alten, entsteht gar kein Write, und <code>SaveData</code> liefert '''False''' - ununterscheidbar von einem echten Fehlschlag.

{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen'''
Datensatz an, statt den vorhandenen zu ändern. Die <code>sys_uid</code> ist der
Schreib-Index und gehört bei jeder Änderung gesetzt.}}

Damit entfällt auch das übliche Paar aus <code>DB_LSeek</code> und
<code>qSqlRead</code>: '''eine''' Abfrage auf die <code>sys_uid</code> liefert
zugleich die Existenzprüfung und den Schreib-Index.

<syntaxhighlight lang="pascal" line>
cUid := '';
if (DB_SOpen(oDB, 'SELECT sys_uid FROM tickets WHERE ' + cWhere + ' LIMIT 1', q)) then begin
if (not q.EoF) then begin
cUid := q.A2UID();
end;
end;
DB_Close(q);

if (not Empty(cUid)) then begin
// ändern: qSqlInit + sys_uid
end else begin
// anlegen: qSqlInit ohne sys_uid
end;
</syntaxhighlight>

===Mehrere Felder sind EIN Schreibvorgang===

Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> entgegen
und schreibt sie mit '''einem''' <code>SaveData</code>. Fallen an derselben
Zeile mehrere Felder an, gehören sie in dasselbe Objekt:

<syntaxhighlight lang="pascal" line>
// FALSCH: fünf Felder, fünf Schreibvorgänge - und jeder Setzer, der sich
// seine sys_uid selbst holt, bringt zusätzlich eine eigene Abfrage mit
FeldSetzen(cUid, 'ti_status' , '9');
FeldSetzen(cUid, 'ti_grund' , cGrund);
FeldSetzen(cUid, 'ti_von' , cBenutzer);

// RICHTIG: ein Schreibobjekt, ein SaveData
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cUid);
q.qSet('ti_status', '9');
q.qSet('ti_grund' , cGrund);
q.qSet('ti_von' , cBenutzer);
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln
end;
qSqlFree(q);
</syntaxhighlight>

Das ist nicht nur eine Frage der Geschwindigkeit: einzeln geschriebene Felder
sind '''nicht atomar'''. Bricht der dritte Schreibvorgang ab, steht die Zeile
halb geändert da - Grund gesetzt, Zeitpunkt nicht.

Wird nichts gesetzt, darf auch nicht geschrieben werden: das Schreibobjekt dann
mit <code>qSqlFree</code> freigeben, statt ein leeres <code>SaveData</code>
abzusetzen.

{{Hinweis|Ein Setzer für '''ein''' Feld (<code>FeldSetzen(cUid, cFeld, cWert)</code>)
ist bequem und deshalb verführerisch. Er versteckt aber je Aufruf eine eigene
Abfrage und ein eigenes <code>SaveData</code>. Für einen Vorgang mit mehreren
Feldern gehört ein '''Editier-Helfer''' her, der das Schreibobjekt liefert -
geschrieben wird einmal am Ende.}}

===Keine Abfrage je Zeile===

Was in einer Liste je Zeile nachgeschlagen wird, kostet '''N''' Abfragen für
'''eine''' Antwort. Bei fünfzig Aufträgen sind das fünfzig Abfragen für ein
einziges Feld. Der Ausweg ist immer derselbe:

* Werte aus einer 1:1-Beziehung über einen <code>LEFT JOIN</code> mitnehmen - bei einem '''eindeutigen''' Index auf dem Join-Feld kann er die Zeilen nicht vervielfachen.
* Einzelwerte aus einer 1:n-Beziehung über eine '''Unterabfrage''' in der SELECT-Liste holen, nicht über einen Join (der Join würde die Zeilen vervielfachen).
* Eine echte Unterliste (Positionen, Dateien) nur dann nachladen, wenn ein '''Zählfeld''' in der Hauptabfrage sagt, dass es überhaupt eine gibt.

{{Hinweis|Ein GET soll '''lesen'''. Schreibvorgänge im Lesepfad - etwas
"beim ersten Ausliefern festschreiben" - vervielfachen sich mit der Zeilenzahl
und treffen den Aufrufer, der nur eine Liste angefordert hat.}}

===Schreibfehler erkennen===

'''<code>SaveData</code> liefert einen Boolean - und der ist die einzige
Fehlermeldung, die es gibt.''' (Auch der '''Parameter''' ist ein Boolean:
''NEW_RECORD'' und ''UPDATE_RECORD'' sind Wahrheitswerte, keine Zahlen.) Schlägt das Schreiben in der Datenbank fehl
(''Duplicate entry'' auf einem eindeutigen Index, zu langer Wert, fehlende
Spalte), dann

* wird '''keine''' Exception ausgelöst,
* steht '''nichts''' in ''RESTSRV_PROTO'',
* läuft das Skript weiter und antwortet mit dem Erfolg, den es selbst formuliert.

Wer den Aufruf als Anweisung schreibt, baut damit einen stillen Datenverlust ein.
Weil in einem Endpunkt schnell ein Dutzend Schreibvorgänge zusammenkommen, gehört
die Prüfung in eine eigene kleine Prozedur - am besten in die gemeinsame Lib:

<syntaxhighlight lang="pascal" line>
procedure Speichern(q: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
begin
lOk := q.SaveData(lNeu);
qSqlFree(q); // auch im Fehlerfall freigeben
if (not lOk) then begin
raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
end;
end;

// Aufruf statt SaveData + qSqlFree:
q := qSqlInit(oDB, 'tickets');
q.qSet('ti_betreff', cBetreff);
Speichern(q, NEW_RECORD, 'Ticket');
</syntaxhighlight>

Die Exception fängt der Server: er schreibt ''Schreiben fehlgeschlagen: Ticket''
nach '''RESTSRV_PROTO''' und antwortet mit '''500'''. Liegt ein
''Idempotency-Key'' an, wird er dabei '''freigegeben''' - die Anfrage ist also
wiederholbar (siehe Abschnitt Idempotenz).

{{Hinweis|Ein fehlgeschlagenes Schreiben ist kein Fall, in dem ein Endpunkt
sinnvoll weiterlaufen kann: die Fachwirkung ist dann unvollständig. Wer trotzdem
weitermachen will - etwa weil mehrere unabhängige Sätze geschrieben werden -,
prüft den Rückgabewert und baut selbst eine Antwort. Ignorieren darf man ihn
nie.}}

Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.

==Gemeinsamen Code auslagern==

Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:

<pre>
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</pre>

{| class="wikitable"
! Attribut !! Bedeutung
|-
| '''T''' || Tabelle, aus der geladen wird
|-
| '''I''' || Spalte, über die gesucht wird
|-
| '''V''' || Wert, der in dieser Spalte stehen muss
|-
| '''F''' || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}

Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Compiler sieht danach den zusammengesetzten Text - eine Funktion aus der Lib lässt
sich also aufrufen wie eine im Skript selbst geschriebene.

===Bewährtes Muster: Lib als eigene Endpunkt-Zeile===

Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
RESTSRV_ENDPOINTS''' abzulegen:

# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
# Den Lib-Quelltext ins Skript-Feld dieser Zeile schreiben (F7).
# '''Keine Berechtigung''' in der Berechtigungs-Liste vergeben - das ist der Schutz: ohne Berechtigung beantwortet der Server einen Aufruf mit 403.
# In jedem nutzenden Endpunkt die Direktive oben einfügen.

Damit ist die Lib reiner Ablageort und von aussen nicht nutzbar. Eine Änderung
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
angefasst werden muss.

{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Funktion hinzu, genügt es nicht, nur das nutzende Skript zu aktualisieren. Eine
ältere Lib lädt fehlerfrei - der Compiler meldet dann ausschliesslich die neuen
Namen als ''Unknown name'', was leicht wie ein Fehler im Skript aussieht.}}

{{Hinweis|Auch hier greift der Endpunkt-Cache: eine Änderung an der Lib wird erst
nach Ablauf des TTL (bis zu 60 Sekunden) wirksam.}}

===Wohin gehört welcher Code?===

Drei Ebenen, und die Zuordnung entscheidet, wie schnell eine Änderung wirkt:

{| class="wikitable"
! Art des Codes !! Wohin !! Wirksam
|-
| Fachlogik **einer** Anwendung - Feldnamen, Zustandswerte, Rollenregeln, Schreibziele || in die '''DWS-Lib dieser Anwendung''' (eigene Endpunkt-Zeile, per <code>{$L …}</code> eingebunden) || nach Ablauf des Cache-TTL, ohne Build
|-
| Mechanik, die '''mehrere''' Anwendungen brauchen - und auch das OBS-Umfeld || nach '''obs_lib''' als Delphi-Unit || erst nach Build und Rollout
|-
| Mechanik, die '''nur''' der REST-Server braucht || in die Units des Servers || erst nach Build und Rollout
|}

Die Regel hat einen praktischen Grund und keinen ästhetischen: Fachlogik ändert
sich in Tagen, Mechanik in Monaten. Was in der Lib liegt, ist nach einer Minute
aktiv; was in einer Unit liegt, braucht einen Build. Wer Fachlogik nach unten
schiebt, tauscht Geschwindigkeit gegen nichts ein.

{{Hinweis|Eine Anwendung, die ihre eigene Lib hat, kopiert sie '''nicht''' von
einer anderen. Zwei Kopien derselben Lib driften auseinander, und die Abweichung
fällt erst auf, wenn eine der beiden Anwendungen etwas Falsches tut. Geteiltes
gehört eine Ebene tiefer.}}

==Fallstricke im Skript==

Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:

{| class="wikitable"
! Stolperstein !! Richtig
|-
| ''DB_SOpen('Y00…', oDB, …)'' - der AD-UID-Parameter aus dem Delphi-Code || Im Skript '''ohne UID''': <code>DB_SOpen(oDB, cSql, q)</code>. Gleiches gilt für <code>qSqlInit(oDB, 'tab')</code> und <code>qSqlRead(oDB, 'tab', cWhere)</code> - jede dieser Funktionen beginnt mit ''oDB''
|-
| ''oReader.Str<T>(…)'' oder irgendein Generic || Generics gibt es in der Skriptsprache nicht. Die Leser sind je Typ eigene Methoden: ''Str'', ''Int'', ''Num'', ''Bool''
|-
| Eine eigene Prozedur ''Delete'' für DELETE || ''Delete'' ist eine '''Standardprozedur''' der Sprache. Die Deklaration lässt sich nicht übersetzen, und die Meldung nennt nur die Zeile - nicht die Ursache
|-
| Ein Helfer, der ein JSON-Fragment als String zurückgibt || Den '''Writer als Parameter''' übergeben und an der richtigen Stelle hineinschreiben. Fragmente von Hand zusammenzusetzen ist genau der Weg, auf dem die Reihenfolge und die Klammern verloren gingen
|-
| ''oWriter.ArrEnd'' nach ''RootArr'' || ''RootArr'' öffnet '''keine''' Ebene, es bestimmt nur die Klammer der Wurzel. Ein ''ArrEnd'' dazu ist ein Strukturfehler
|-
| Zahlen selbst formatieren (''NStr'', ''StrTran'') || <code>oWriter.Num('preis', nWert, 2)</code>. Selbst formatiert stand bei Werten ab 1000 der Tausendertrenner im JSON - gültiges JSON, falscher Wert, keine Meldung
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'|' + wert + '|'</code>) und mit ''Pos'' prüfen
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
|-
| <code>q.SaveData(…)</code> als Anweisung schreiben || ''SaveData'' liefert einen '''Boolean'''. Ein SQL-Fehler beim Schreiben wirft '''keine''' Exception und landet in '''keinem''' Protokoll - der Rückgabewert ist die einzige Meldung. Immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Je Feld ein eigener Setzer-Aufruf || Ein <code>qSqlInit</code>-Objekt, beliebig viele <code>qSet</code>, '''ein''' <code>SaveData</code>. Einzeln geschrieben kostet jedes Feld eine eigene Abfrage samt eigenem Write - und der Vorgang ist nicht mehr atomar, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Ein Wert je Zeile nachgeschlagen || In einer Liste sind das N Abfragen für eine Antwort. Über <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n) mitnehmen, siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]]
|-
| Ausgabeparameter vom Typ <code>var … : TDateTime</code> || Bringt die Skript-VM zum '''Absturz''' (Assertion in ''dwsStack.pas''), und zwar beim ersten '''Lesen''' des Werts - nicht schon beim Schreiben, die Ursache liegt also nicht dort, wo der Fehler auffällt. <code>var string</code>, <code>var Integer</code> und <code>var Double</code> laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und erst beim Aufrufer wandeln
|}

==Skript-Cache==

Der Server cached das kompilierte Skript pro Endpunkt (Schlüssel: ''sys_date'' des Endpunkts). Zusätzlich werden die Endpunkt-Definitionen pro Server-Profil in einem TTL-Cache (Standard 60 s) gehalten. Eine Skript-Änderung über F7 wird daher erst nach Ablauf dieses TTL (bzw. nach einer Cache-Invalidierung) wirksam - typischerweise innerhalb einer Minute, nicht zwingend sofort.

==Verfügbare Bibliotheken==

Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:

* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
* ''Base.qSqlReg'' - Schreibzugriffe
* ''lib_ScriptIO'' - Writer und Reader, siehe unten. '''System.JSON braucht ein Endpunkt-Skript nicht''' - der Writer erzeugt die Antwort, der Reader liest den Körper
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''
* ''lib_ScriptIO'' - ''TxRestWriter'', ''TxRestReader'' und die Zeitfunktionen ''RestIsoFromDate'' / ''RestDateFromIso'' / ''RestOffsetToMinutes''. Writer und Reader bekommt das Skript als Parameter; die Zeitfunktionen ruft es direkt

Die wichtigsten Aufrufe mit ihren Skript-Signaturen:

{| class="wikitable"
! Zweck !! Aufruf
|-
| Lesen || <code>DB_SOpen(oDB, cSql, q)</code>, dann <code>q.EoF</code>, <code>q.Next()</code>, <code>q.A2C('feld')</code> / <code>A2I</code> / <code>A2F</code> / <code>A2D</code> / <code>A2UID()</code>, am Ende <code>DB_Close(q)</code>
|-
| Neu anlegen || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('feld', wert)</code>, <code>if (not q.SaveData(NEW_RECORD)) then …</code>, <code>qSqlFree(q)</code> – der Rückgabewert ist Pflicht, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Ändern || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('sys_uid', cUid)</code>, <code>q.qSet(…)</code>, <code>if (not q.SaveData(UPDATE_RECORD)) then …</code>, <code>qSqlFree(q)</code> – '''nicht''' <code>qSqlRead</code>, siehe [[#Ändern: qSqlInit statt qSqlRead|Ändern]]. Alle Felder derselben Zeile in '''ein''' Objekt, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
|-
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
|}

{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
Skript nicht übersetzen.}}

Konkrete Beispiele:

* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

OBS/Kostenpflichtige Module/RESTServer/Endpunkte

2026-09-14T08:07:29Z

Rademacker:

{{Kostenpflichtige Module}}

= Endpunkte =

Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
realisiert und ist genau einem Server-Profil zugeordnet.

== Routing über Pfad-Templates ==

Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
'''Platzhalter''' enthalten:

* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
* '''Platzhalter''' in geschweiften Klammern – z. B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.

Beispiele für gültige Templates:

{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}

=== Präzedenz bei mehreren Treffern ===

Passen mehrere Templates auf denselben Pfad, '''gewinnt das spezifischste''' –
also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code>
das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf
<code>/orders/{uid}</code> matcht.

== Hauptfelder eines Endpunkts ==

{| class="wikitable"
! Feld !! Spalte !! Zweck
|-
| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code>
|-
| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
|-
| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
|-
| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
|-
| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
|-
| '''Info''' || – || Dokumentations-Freitext
|-
| '''Datei-Upload''' || <code>re_upload</code> || Erlaubt Datei-Uploads an diesem Endpunkt (<code>0</code> = aus, <code>1</code> = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
|-
| '''Max. Upload-Grösse''' || <code>re_upload_size</code> || Maximale Dateigrösse in MB. Leer/0 = Standard 25 MB. Überschreitung wird mit 413 abgelehnt.
|}

== Pfad-Parameter im Skript ==

Die aus den Platzhaltern erfassten Werte liest das Endpunkt-Skript über
<code>oReader.Path</code>:

<syntaxhighlight lang="pascal">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
cUid := oReader.Path('uid'); // aus /orders/{uid}
// ...
end;
</syntaxhighlight>

Diese Werte stammen aus dem Routing und können nicht durch den Client
überschrieben werden.

== Datei-Uploads ==

Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.

Die maximal zulässige Dateigrösse wird pro Endpunkt über <code>re_upload_size</code>
(in MB) festgelegt; ohne Angabe gilt der Standard von '''25 MB'''. Wird das
Limit überschritten, antwortet der Server mit '''413 Payload Too Large'''. Für
Uploads gilt nicht das JSON-Body-Limit (10 MB), sondern dieses Endpunkt-Limit.
Der Originalname (beim resumable Upload über den Header <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit 413/400 abgelehnt. Das Skript liest Pfad, Name, Content-Type und die SHA-256-Prüfsumme der gespeicherten Datei über <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code> und <code>UploadSha()</code>; bei <code>multipart/form-data</code> die übrigen Formularfelder über <code>oReader.Form('<name>')</code>.

'''Das Übertragungsprotokoll''' - Header, Statuscodes, Resume-Verhalten - steht auf einer eigenen Seite: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].

Unterstützt werden zwei Übertragungsarten:

* '''Einfacher Upload''' per <code>multipart/form-data</code> (eine Datei pro Request).
* '''Resumable/Chunked Upload''' per <code>Content-Range</code> (grosse Dateien, fortsetzbar nach Abbruch).

Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und
übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage,
DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und
Beispiele: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Datei-Downloads ==

Ein Endpunkt kann eine '''Datei''' statt eines JSON-Körpers zurückgeben -
PDF, CSV, eine APK. Dafür ist '''keine Freischaltung''' nötig: ein Download
entsteht dadurch, dass das Skript ihn mit <code>oWriter.SendFile(...)</code>
bzw. <code>oWriter.SendTempFile(...)</code> erzeugt, nicht dadurch, dass ein
Client ihn anfragt.

Content-Type, Dateiname, Bereichsanfragen (<code>Range</code>, '''206'''),
ETag und das Aufräumen temporärer Dateien übernimmt der Server. Einzelheiten:
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].

== HTTP-Methode ==

Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
Pfad-Formen (z. B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
'''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.

== URL-Struktur ==

<pre>
http://[Host][:Port][Pfad-Template]
</pre>

Beispiele:
* <code>https://api.meinserver.de/orders</code>
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>

== Versionierung ==

Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z. B. <code>/orders/v1</code> oder
<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:

# Bestehenden Endpunkt unverändert lassen.
# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
# Berechtigungen für neue Konsumenten setzen.
# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.

== Zugriffskontrolle ==

Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
dürfen.

{{Achtung|'''Ein Endpunkt besteht aus zwei Zeilen, und beide werden von Hand
gepflegt:''' der Eintrag in <code>RESTSRV_ENDPOINTS</code> und die Berechtigung
in <code>RESTSRV_ACCESS</code>. Fehlt die zweite, antwortet der Endpunkt
'''403''' - und sieht dabei fertig aus: Pfad, Skript und Server-Profil stehen
korrekt da, der Aufruf kommt trotzdem nicht durch. Das ist die häufigste Ursache
für ein „der Endpunkt ist doch angelegt" und kostet jedes Mal eine
Fehlersuche, weil der Statuscode nach einem Rechteproblem des Konsumenten
aussieht und nicht nach einer fehlenden Konfigurationszeile.

Beim Anlegen also '''immer beide Zeilen''', und beim Prüfen eines
<code>403</code> zuerst nachsehen, ob die zweite existiert.}} Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
Zugriff '''pro Pfad-Form''' granular vergeben (z. B. Lesen von
<code>/orders/{uid}</code> erlauben, aber das ändernde
<code>PUT /orders/{uid}/modules/{code}</code> nicht).

== Caching ==

Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
(TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher
erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
zwingend sofort.

== HTTP-Fehlercodes ==

{| class="wikitable"
! Code !! Ursache
|-
| '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
|-
| '''403''' || Zugang fehlt in der Berechtigungsliste
|-
| '''401''' || API-Key ungültig/fehlend, JWT abgelaufen oder Sitzung gesperrt (''AUTH_EXPIRED'')
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
|-
| '''405''' || Das Endpunkt-Skript hat für die angefragte HTTP-Methode keine Funktion; der Header <code>Allow</code> nennt die vorhandenen
|-
| '''206''' || Teilantwort eines Datei-Downloads auf eine <code>Range</code>-Anfrage; die Antwort enthält <code>Content-Range</code>
|-
| '''416''' || Der angefragte <code>Range</code> liegt hinter dem Dateiende; die Antwort nennt in <code>Content-Range</code> die wirkliche Grösse
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>)
|-
| '''429''' || Rate-Limit überschritten; die Antwort enthält den Header <code>Retry-After</code>
|-
| '''503''' || Eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet; die Antwort enthält <code>Retry-After</code>
|-
| '''409''' || Ein früherer Aufruf mit demselben <code>Idempotency-Key</code> ist ohne Ergebnis geblieben (<code>IDEMPOTENCY_UNRESOLVED</code>)
|-
| '''422''' || Derselbe <code>Idempotency-Key</code> wurde mit '''anderem''' Inhalt gesendet (<code>IDEMPOTENCY_KEY_REUSED</code>)
|-
| '''400''' || Die Anfrage wurde unverschlüsselt an einen TLS-Port geschickt (<code>http</code> statt <code>https</code>). Die Abweisung erfolgt vor Authentifizierung und Endpunkt-Skript
|}

Jede Fehlerantwort besteht aus einem <code>error</code>-Objekt mit
maschinenlesbarem Code - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. <code>201</code>, <code>204</code>, <code>409</code>, <code>422</code>) sowie Response-Header wie <code>ETag</code> oder <code>Location</code> - siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Idempotenz ==

Schickt ein Konsument bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code>
oder <code>DELETE</code> den Header <code>Idempotency-Key</code>, sorgt der Server
selbst dafür, dass eine wiederholte Sendung '''keine Zweitwirkung''' hat. Das gilt
für '''jeden''' Endpunkt - es muss weder am Endpunkt etwas eingestellt noch im
Skript etwas programmiert werden.

{| class="wikitable"
! Situation !! Antwort des Servers
|-
| Erster Aufruf || Endpunkt läuft normal, das Ergebnis wird zum Schlüssel gespeichert
|-
| Wiederholung, gleicher Inhalt || '''Gespeicherte Antwort''' (gleicher Statuscode, gleicher Body, gleiche Header) plus Header <code>Idempotent-Replay: true</code>. Das Skript läuft '''nicht'''
|-
| Wiederholung, anderer Inhalt || '''422''' <code>IDEMPOTENCY_KEY_REUSED</code> - derselbe Schlüssel für einen anderen Inhalt ist ein Client-Fehler
|-
| Erster Aufruf läuft noch || '''503''' <code>IDEMPOTENCY_IN_PROGRESS</code> mit <code>Retry-After</code>. Beim nächsten Versuch liegt die gespeicherte Antwort vor
|-
| Früherer Aufruf ohne Ergebnis || '''409''' <code>IDEMPOTENCY_UNRESOLVED</code>. Nur noch nach einem '''harten Abbruch''' des Dienstes zwischen Verarbeitung und Festschreiben; ob die Buchung stattgefunden hat, ist unbekannt. Der Aufräumlauf gibt solche Einträge nach 24 Stunden frei und protokolliert sie
|}

Wichtig für die Auslegung eines Endpunkts:

* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* Antwortet das Skript mit '''4xx''' (fachliche Ablehnung), wird der Schlüssel wieder '''freigegeben''' - der Konsument darf ihn nach Korrektur erneut verwenden. Sonst würde ein einziger Validierungsfehler den Schlüssel dauerhaft blockieren.
* Endet die Verarbeitung mit '''5xx''' oder einem Skript-Fehler, wird der Schlüssel '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden.
* Das ist eine bewusste Abwägung (geändert 2026-08-25): Bleibt der Schlüssel nach einem Serverfehler belegt, ist der Vorgang '''unwiederholbar''' - der Client bekommt dauerhaft 503 und müsste die erfasste Arbeit verwerfen. Garantierter Datenverlust wiegt schwerer als ein möglicher Doppelsatz.
* '''Folge für die Auslegung:''' ein schreibender Endpunkt sollte selbst wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.

Der Schlüssel gilt je '''Zugang, Methode und Pfad'''. Derselbe
<code>Idempotency-Key</code> an einem anderen Endpunkt ist damit ein eigener
Vorgang - der Konsument muss ihn nicht global eindeutig vergeben, aber pro Vorgang
'''stabil wiederverwenden''' (also nicht bei jedem Wiederholversuch neu erzeugen).

Die Einträge stehen in <code>RESTSRV_IDEMPOTENCY</code> und werden nach 30 Tagen
automatisch aufgeräumt. Einträge ohne Ergebnis werden '''nicht''' automatisch
gelöscht, sondern im Protokoll gemeldet.

== WebHooks ==

WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
gespeichert und der Endpunkt anschließend automatisch gelöscht.

Typischer Einsatz: OBS stösst einen Vorgang bei einem Fremdsystem an (Bezahldienst,
Versanddienstleister) und gibt diesem eine Rückruf-Adresse mit, die nur '''ein
einziges Mal''' gültig ist. Damit kann die Adresse nicht später erneut - oder von
jemand anderem - benutzt werden.

Ablauf:

# OBS legt einen Eintrag in <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, dessen Feld '''WebHook''' (<code>re_webhook</code>) auf diesen Eintrag zeigt. Ein Skript wird für diesen Endpunkt nicht gepflegt.
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
# Das Fremdsystem ruft die Adresse auf. Der Server legt den übergebenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code> ab, antwortet mit <code>{"status": "ok"}</code> und '''löscht den Endpunkt'''.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.

{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
normalen Endpunkt mit Skript anlegen.}}

OBS/Kostenpflichtige Module/RESTServer/Zugaenge

2026-09-14T08:07:19Z

Rademacker:

{{Kostenpflichtige Module}}

=Zugänge=

Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''

==Felder==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Name || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
| CORS-Origins || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt. '''Leer heisst nicht „keine Einschränkung", sondern „kein Browser-Zugriff"''' - siehe unten
|-
| mTLS-Subject || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
|-
| JWT || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
| JWT-Endpunkt || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
|-
| JWT-Key || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
| JWT-Exp || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
|}

==API-Key==

Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:

apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12

Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.

{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}

{{Achtung|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt der
Endpunkt weder Mandant noch Rolle - es gibt nichts, woran er eine Berechtigung
festmachen könnte ausser dem, was in der URL steht. Ein Wildcard-Zugang eignet
sich deshalb für Artefakte, die für jeden bestimmt sind (Test-APK, Handbuch),
'''nicht''' für Kundenbelege. Siehe
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].}}

{{Hinweis|Bei einem Wildcard-Zugang sollte ''CORS-Origin'' '''leer''' bleiben.
Ein ''*'' dort wirkt auf die Preflight-Antwort '''aller''' Zugänge (siehe unten);
ein Download über die Adresszeile des Browsers sendet ohnehin kein ''Origin'',
CORS greift dort also gar nicht.}}

==Host-Beschränkung==

Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.

==CORS==

Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.

Format der Liste:

https://app.kunde.de;https://test.kunde.de;https://localhost:8080

Ablauf:

# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste '''aller''' Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste '''des aktuell verwendeten Zugangs''' geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.

Der Preflight kann nicht zugangsbezogen prüfen: der Browser schickt dabei keinen
''apikey'' mit, der Zugang ist zu diesem Zeitpunkt unbekannt. '''Die Durchsetzung
liegt deshalb auf Schritt 2''', nicht auf dem Preflight. Praktische Folge: trägt
'''ein''' Zugang auf dem Server ein ''*'' in seiner Liste, antwortet jeder
Preflight mit ''Access-Control-Allow-Origin: *'' - auch für Zugänge mit engerer
Liste. Deren eigentliche Anfrage wird trotzdem gegen die eigene Liste geprüft.

Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH'' (systemseitig festgelegt).

Bei den '''Anfrage-Headern''' spiegelt der Server im Preflight zurück, was der
Browser in ''Access-Control-Request-Headers'' angefragt hat. Damit sind eigene
Header eines Projekts - ''Idempotency-Key'', ''If-Match'', später
''Upload-Offset''/''Upload-Length'' - ohne Änderung am Server nutzbar. Fragt der
Preflight keine Header an, antwortet der Server mit der Liste
''Content-Type, apikey, Authorization, Accept''.

{{Hinweis|Die Header-Liste ist '''keine Schutzgrenze''' - das ist das Origin. Sie
sagt dem Browser nur, welche Header der Server versteht. Dazu kommt, dass die
Zugangsdaten dieser Schnittstelle in Headern stehen (''apikey'',
''Authorization'') und nicht in Cookies: es gibt also keine automatisch
mitgeschickte Berechtigung, die eine fremde Seite ausnutzen könnte.}}

===Was „leer" bedeutet===

{{Achtung|Ein '''leeres''' Feld CORS-Origins heisst '''nicht''' „keine
Einschränkung". Es heisst: '''jeder Aufruf mit ''Origin''-Header wird mit 403
abgelehnt'''. Für Clients '''ohne''' ''Origin''-Header - mobile Apps, Server,
curl - ändert das Feld gar nichts, sie werden nie gegen CORS geprüft.}}

Daraus ergeben sich drei sinnvolle Einstellungen:

{| class="wikitable"
! Feld !! Wirkung
|-
| leer || Kein Browser-Zugriff. Richtig für Zugänge, die nur von Apps oder Servern benutzt werden
|-
| konkrete Origins || Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen
|-
| ''*'' || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antwort aller anderen Zugänge - bewusst und sparsam verwenden
|}

Für eine Browser-Anwendung ist dieses Feld besonders wichtig, weil ihr API-Key
zwangsläufig im JavaScript liegt und damit öffentlich ist. Die Origin-Liste
verhindert dann, dass jemand den Key nimmt und von seiner eigenen Seite benutzt.
Sie ist allerdings kein Ersatz für eine Zugriffskontrolle: wer den Key hat,
umgeht CORS mit einem einzigen Aufruf ausserhalb des Browsers.

==JWT-Authentifizierung==

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).

'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.

Unterschieden wird nach Verb und Token-Art:

{| class="wikitable"
! Aufruf !! Ablauf
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
|}

{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}

===Phase 1: Token-Bezug===

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Body: {"username":"...", "password":"..."}

Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Prozedur ''Authenticate'' bereitstellen, die über den Writer schreibt:

* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_<name>'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)

Die Signatur lautet ''procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);'' - Details unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 28800,
"serverTime": "2026-06-29T15:30:12+02:00"}

Zum Aufbau der Antwort:

* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.

Beispiel mit Zusatzfeldern aus dem Skript:

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
"expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}

Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.

Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''' und reicht den Text aus dem Feld ''error'' als
''error.message'' an den Client durch - der Konsument kann ihn also direkt
anzeigen. Die Formulierung liegt damit beim Skript.

{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}

===Phase 2: Token-Verwendung===

Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:

GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi...

Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.

Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.

{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}

===Phase 3: Token erneuern (Refresh)===

Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Refresh-Token)

Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}

Verhalten bei einem bereits benutzten Refresh-Token:

{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
|}

Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

===Phase 4: Abmelden (Logout)===

Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
Access-Token im ''Authorization''-Header:

DELETE https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Access-Token)

HTTP/1.1 204 No Content

Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.

* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.

====Alle Geräte abmelden====

Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
''oWriter.JwtRevoke'', das jeder gewöhnliche Endpunkt aufrufen kann:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('all');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}

==Woher ein Anmelder seine Identität bekommt==

'''Diese Frage entscheidet das Skript des Zugangs, nicht der Server.''' Das
Authentifizierungs-Skript liegt je Zugang in <code>ra_jwt_script</code> - und
damit gilt für jede Anwendung ihre eigene Regel.

Das ist keine Kleinigkeit, sondern der Punkt, an dem sich zwei Anwendungen
unterscheiden. Ein Beispiel aus dem Betrieb: Ein Zugang für eine
Techniker-Anwendung lehnt jeden Benutzer ohne Mitarbeiterzuordnung
(<code>BENUTZ.b_mitarbeiter</code>) ab - '''bewusst''', denn ein Techniker ohne
Zuordnung bekäme eine leere Auftragsliste und würde den Fehler bei sich suchen.
Für einen Kundenzugang wäre genau dieselbe Regel falsch: sie träfe '''jeden'''
Anmelder.

Wer einen zweiten Zugang für eine andere Anwendung anlegt, prüft deshalb als
Erstes: Woraus besteht die Identität dieser Anmelder, und welche Ablehnung ist
für sie richtig? Ein kopiertes Skript bringt die Regel der anderen Anwendung
mit, und sie fällt erst auf, wenn sich der erste echte Anmelder nicht anmelden
kann.

==Sitzungen (RESTSRV_TOKEN)==

Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt".

* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.

==mTLS-Subject-Prüfung==

Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.

Beispiele für Subject-Strings im Cert (OneLine-DN):

/C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
/C=DE/O=Kunde GmbH/CN=client-test.kunde.de

Mit '''CN=client-prod.kunde.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Kunde GmbH;CN=client-prod.kunde.de''.

==Listen-Funktionen==

In der Zugänge-Liste (allein):

* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang

Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):

* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

OBS/Kostenpflichtige Module/RESTServer/Server-Profile

2026-09-14T08:07:07Z

Rademacker:

{{Kostenpflichtige Module}}

=Server-Profile=

Ein '''Server''' im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.

Typische Einsatzfälle für mehrere Profile:

* Ein '''Public-Profil''' mit Standard-TLS auf Port 443 für externe Konsumenten.
* Ein '''Internal-mTLS-Profil''' auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
* Ein '''Debug-Profil''' mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server'''

==Felder des Server-Profils==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Nr || Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
|-
| Name || Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
|-
| Aktiv || Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
|-
| Info || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
|-
| Kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
|-
| mTLS || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
|-
| Cert || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
|-
| Key || PEM-Inhalt des privaten Schlüssels
|-
| Root-Cert || PEM-Inhalt des CA-Root-Zertifikats (Pflicht bei Standard-TLS, dort für Chain-Validierung, sowie bei mTLS, dort zusätzlich für Client-Cert-Verifikation)
|-
| Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
|-
| Limit Erfolg || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
|-
| Limit Fehler || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
|-
| Limit gesamt || Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
|-
| Max. Verbindungen || Obergrenze gleichzeitiger '''Verbindungen''' (<code>rsv_max_conn</code>). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server '''ohne HTTP-Antwort''' - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
|-
| Max. parallel || Obergrenze gleichzeitig '''verarbeiteter Anfragen''' (<code>rsv_max_parallel</code>). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server '''503''' mit <code>Retry-After</code>, der Client darf es also gleich erneut versuchen
|}

Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.

==Modi==

{| class="wikitable"
! Modus !! Voraussetzungen !! Anwendung
|-
| '''Standard-TLS''' || Cert + Key + Root-Cert hinterlegt || Empfohlener Default für alle Server, die über das öffentliche Netz erreichbar sind
|-
| '''mTLS''' || Cert + Key + Root-Cert (CA) || Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
|-
| '''Plain-HTTP''' || Haken ''Kein SSL'' || Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt
|}

Beide Richtungen werden erkannt: Eine '''unverschlüsselte Anfrage an einen
TLS-Port''' (''http'' statt ''https'') beantwortet der Server mit '''HTTP 400'''
und einem Klartext-Hinweis. Die Abweisung erfolgt '''vor''' Authentifizierung,
Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also
keine Verarbeitung aus.

{{Hinweis|Bei Standard-TLS und mTLS fährt der Server ohne Cert/Key gar nicht erst hoch. Bei Standard-TLS ohne Root-Cert wird die Anlage abgelehnt - die Chain-Validierung benötigt das CA-Root. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.}}

==TLS-Version, Cipher und Zertifikats-Rotation==

* '''TLS-Version:''' Der Server erzwingt '''TLS 1.2'''. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
* '''Rotation:''' Ein Zertifikatswechsel erfolgt durch ändern der PEM-Inhalte in der DB und einen '''Neustart''' des REST-Dienstes (kein Hot-Reload). Bis zum Neustart läuft das alte Zertifikat weiter.
* '''Certificate-Pinning:''' Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher '''rechtzeitig ankündigen''' und mit einem '''Backup-Pin''' vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus.
==Rate-Limit je Profil==

Jedes Server-Profil führt '''eigene Zähler''' und kann '''eigene Schwellen''' haben.
Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit
aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.

Gezählt wird pro Schlüssel, und der Schlüssel ist der '''API-Key''' des Zugangs.
Sendet ein Konsument keinen API-Key (Zugang mit ''*''), wird ersatzweise auf die
'''IP-Adresse''' gezählt.

{{Hinweis|Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle
Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen
API-Key, teilen sich '''alle Benutzer einen Zähler'''. Mit den Standardwerten sind
das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen
Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst
höher setzen oder jedem Konsumenten einen eigenen API-Key geben.}}

Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden
'''beim Start''' des REST-Dienstes gelesen - eine Änderung wird erst nach einem
Neustart wirksam.

==Validierung beim Speichern==

Beim Speichern wird geprüft:

* Nr und Name müssen vergeben sein.
* Nr muss eindeutig sein.
* Name muss eindeutig sein.
* Bei nicht aktiviertem ''Kein SSL'' müssen Cert und Key vorhanden sein.
* Bei nicht aktiviertem ''mTLS'' (= Standard-TLS) muss Root-Cert vorhanden sein.

==Bindungen==

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.

===Aufruf===

In der Server-Liste den gewünschten Server markieren und '''F6''' drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.

===Felder===

{| class="wikitable"
! Feld !! Beschreibung
|-
| Host || IP-Adresse oder Hostname, auf dem gelauscht wird. ''0.0.0.0'' = alle IPv4-Adressen; ''127.0.0.1'' = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
|-
| Port || TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
|-
| Aktiv || Bindung wird beim Server-Start geladen
|-
| Standard|| Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt
|}

===Wirksamkeit===

Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.

==Listen-Funktionen==

In der Server-Liste:

* '''Einfg''' - neues Server-Profil
* '''Return''' - vorhandenes Profil bearbeiten
* '''F4''' - Sortierung wählen
* '''F6''' - Bindungs-Liste des markierten Servers

OBS/Kostenpflichtige Module/RESTServer

2026-09-14T08:06:51Z

Rademacker:

{{Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

Der REST-Server ist die '''universelle Schnittstelle''' Ihrer OBS-Installation nach außen. Er macht aus Ihrem OBS einen Dienst, mit dem andere Programme - Webseiten, Apps, Geräte, Kundensysteme, Cloud-Dienste - direkt sprechen können. Statt Daten manuell zu exportieren, zu mailen oder über Umwege bereitzustellen, holen sich angebundene Systeme genau die Information, die sie brauchen, in dem Moment, in dem sie sie brauchen - oder liefern neue Daten direkt in OBS ab.

Für Anwender, die nicht selbst programmieren, bedeutet das: '''Was bisher nur manuell, per Datei-Import oder über Spezialschnittstellen ging, lässt sich jetzt automatisieren.''' Eine Webseite zeigt live aktuelle Lagerbestände. Mitarbeiter erfassen Zeiten über das Handy, ohne dass jemand Excel-Listen einpflegen muss. Ein Kunde stößt per Bestelltaste in seinem System einen Vorgang in Ihrem OBS an. Ein Lieferant meldet Wareneingänge automatisch zurück. Jeder dieser Anwendungsfälle wird einmal eingerichtet und läuft danach automatisch.

Technisch gesehen ist der REST-Server ein in OBS integrierter, voll konfigurierbarer '''HTTP/HTTPS-Dienst''', dessen Endpunkte über in OBS gepflegte Pascal-Skripte realisiert werden. Jeder Endpunkt bekommt eine eigene Adresse, eine eigene Logik und eine eigene Berechtigungsstruktur. Rückgaben erfolgen ausschliesslich im JSON-Format. Damit lassen sich beliebige Lese- und Schreibvorgänge auf der OBS-Datenbank realisieren, ohne dass externe Systeme direkten Datenbank-Zugriff erhalten - das ganze OBS-Regelwerk (Rechte, Validierung, Geschäftslogik) bleibt aktiv.

Im Ergebnis ist der REST-Server kein einzelnes Feature, sondern ein '''Werkzeugkasten''': Was an Daten oder Funktionen in OBS verfügbar ist, kann über den REST-Server auch nach außen angeboten - oder von außen entgegengenommen - werden. Die Bandbreite reicht vom einfachen Lese-Endpunkt für ein Webseiten-Widget bis hin zu kompletten B2B-Integrationen mit Mandanten- und Rollen-Trennung.

Aufruf des Moduls in OBS:
'''Stammdaten''' -> '''Z Weitere Stammdaten''' -> '''REST-Server'''

==Anwendungsbereiche==

Die folgenden Einsatzfälle sind typische Beispiele, an denen sich der praktische Nutzen ablesen lässt. Es ist keine abschliessende Liste - alles, was sich in OBS-Skripten abbilden lässt, kann auch über einen Endpunkt bereitgestellt werden.

{{Hinweis|Dies sind Beispiele. Für die konkrete Entwicklung können, je nach Komplexität, weitere Kosten anfallen.}}

===Webseiten und Kundenportale===

* '''Live-Daten auf der eigenen Webseite:''' Lagerbestände, Verfügbarkeiten, Preise, Auftragsstatus aus OBS direkt anzeigen, ohne tägliche Datei-Exports.
* '''Kundenportale:''' Kunden sehen ihre offenen Posten, Auftragshistorie, Lieferscheine. Die Seite holt sich die Daten zur Anzeigezeit direkt aus OBS, jeder Kunde sieht nur seine eigenen Daten.
* '''Trackingseiten:''' Status einer Bestellung, eines Auftrags oder einer Reparatur für Endkunden, abrufbar über eine Sendungsnummer.

===Mobile Anwendungen und Außendienst===

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''QR-/Barcode-Scanner und Lagergeräte:''' Wareneingang, Inventur, Kommissionierung direkt in OBS abbilden, ohne zwischengeschaltete Software.
* '''Außendienst-Apps:''' Techniker sehen ihre Aufträge, dokumentieren Einsätze, erfassen Material - synchronisiert mit OBS.

===Anbindung von Drittsystemen===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''Buchhaltungs- und ERP-Systeme:''' Bidirektionaler Austausch von Belegen, Stammdaten und Buchungen.
* '''CRM- und Marketing-Tools:''' Personendaten, Aktivitäten oder Mailing-Empfänger werden synchron gehalten.
* '''Logistikdienstleister:''' Versandaufträge werden übergeben, Tracking-Informationen zurückgeliefert.

===Automatisierte Rückmeldungen (WebHooks)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''Versanddienste:''' Statusmeldungen (verschickt, zugestellt, retour) werden direkt im passenden Vorgang dokumentiert.
* '''Cloud-Workflows:''' Externe Automatisierungs-Plattformen (Make, Zapier, n8n, ...) stoßen OBS-Vorgänge an oder werden von OBS aus angesprochen.

===Geschäftspartner-Kommunikation (B2B)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''Kunden-Schnittstelle:''' Grosskunden bestellen direkt aus ihrem ERP heraus, Stammdaten und Konditionen werden zentral gepflegt.
* '''Sichere Maschine-zu-Maschine-Kommunikation:''' Mit Mutual-TLS (mTLS) wird sichergestellt, dass nur die freigeschalteten Partnersysteme - und niemand sonst - mit OBS sprechen können.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''Verbindung mehrerer Standorte:''' Verteilte Systeme tauschen Daten über definierte Endpunkte aus, ohne offene Datenbankverbindungen.
* '''Datenbereitstellung für Dashboards und Auswertungen:''' BI-Tools (Power BI, Grafana, ...) lesen aufbereitete Kennzahlen direkt aus OBS.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''Fehler werden weniger.''' Jede manuelle Stelle ist eine mögliche Fehlerquelle; jede Automatisierung eine Stelle, an der nichts mehr schiefgehen kann.
* '''Neue Geschäftsmodelle werden möglich.''' Kunden- und Lieferantenportale, Self-Service-Funktionen, App-Anbindungen lassen sich aufbauen, ohne ein zweites System pflegen zu müssen.
* '''Bestehende Software bleibt verbunden.''' Statt eine vorhandene Anwendung ablösen zu müssen, kann sie über den REST-Server an OBS angedockt werden - in beiden Richtungen.
* '''Skaliert mit:''' Was klein anfängt (ein einzelner Endpunkt für eine Webseite) kann zu einer kompletten Integrations-Plattform ausgebaut werden, ohne dass die Grundlage gewechselt werden muss.

==Architektur im Überblick==

Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:

{| class="wikitable"
! Baustein !! Tabelle !! Zweck
|-
| Server || RESTSRV_SERVER || TLS-Profil + eigene HTTP-Server-Instanz, kann mehrfach existieren
|-
| Bindung || RESTSRV_BINDINGS || IP-Adresse + Port pro Server
|-
| Zugang || RESTSRV_ACCOUNT || API-Key, optionale Host- und CORS-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| Protokoll || RESTSRV_PROTO || Laufende Ereignisse, Fehler, Audit-Einträge
|-
| Statistik || RESTSRV_STATS || Aufrufzähler, Antwortzeiten und HTTP-Status pro Endpunkt
|}

Eine Anfrage durchläuft folgende Stationen:

# Rate-Limit-Prüfung (pro API-Key bzw. IP und global, Schwellen je Server-Profil)
# Authentifizierung über den API-Key (Header ''apikey'')
# CORS-Prüfung (sofern ''Origin''-Header gesetzt)
# Optional: JWT-Prüfung - Signatur, Ablauf und Sitzung (sofern für den Zugang aktiviert)
# Routing: Auflösung des Pfads über die Pfad-Templates der Endpunkte
# Prüfung der Berechtigung (Zugang -> Endpunkt)
# Idempotenz-Prüfung (nur bei POST/PUT/PATCH/DELETE '''mit''' ''Idempotency-Key''-Header)
# Ausführung des Endpunkt-Skripts (oder WebHook-Antwort)
# Festschreiben des Ergebnisses im Idempotenz-Speicher (sofern in Schritt 7 reserviert)
# JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag

==Adressierung==

Ein Endpunkt wird über ein '''Pfad-Template''' angesprochen, das den Pfad nach dem Host beschreibt und Platzhalter enthalten kann:

http://[Hostadresse][:Port][Pfad-Template]

Beispiele:

https://api.meinserver.de/kalender/v1
https://api.meinserver.de/orders/{uid}
https://api.meinserver.de/orders/{uid}/modules/{code}

Statische Segmente müssen exakt passen; Platzhalter in geschweiften Klammern (z.B. {uid}) matchen einen beliebigen Wert und stehen im Skript als Pfad-Parameter zur Verfügung. Eine Versionskennung wird als statisches Segment ins Template aufgenommen (z.B. /kalender/v1), um eine Funktionalität zu verändern, ohne bestehende Konsumenten zu brechen. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==Unterstützte HTTP-Methoden==

Der Server akzeptiert die Methoden '''GET''', '''POST''', '''PUT''', '''DELETE''' und '''PATCH''' sowie '''OPTIONS''' (CORS-Preflight, ohne Skript-Aufruf). Jede Methode wird im Endpunkt-Skript als gleichnamige Funktion implementiert. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Datei-Uploads==

Endpunkte, die dafür freigeschaltet sind (<code>re_upload</code>), nehmen Dateien
per <code>multipart/form-data</code> oder als fortsetzbaren '''Resumable-Upload'''
(<code>Content-Range</code>) entgegen. Die maximale Grösse wird pro Endpunkt
festgelegt (<code>re_upload_size</code>, Standard 25 MB); Überschreitung
ergibt 413, ein Upload an einen nicht freigeschalteten Endpunkt 415. Der Server
legt die Datei temporär ab und übergibt dem Skript den Pfad; die weitere
Verarbeitung (z.B. DMS-Ablage) übernimmt das Skript. Details:
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Doppelte Sendungen abfangen (Idempotenz)==

Ein Client, der nach einem Timeout dieselbe Anfrage erneut schickt, darf keine
Zweitbuchung auslösen. Der Server erledigt das selbst: Sendet ein Aufruf mit
'''POST''', '''PUT''', '''PATCH''' oder '''DELETE''' den Header
<code>Idempotency-Key</code>, merkt sich der Server Schlüssel und Ergebnis in
'''RESTSRV_IDEMPOTENCY'''. Eine Wiederholung mit demselben Schlüssel und demselben
Inhalt bekommt die '''gespeicherte Antwort''' zurück - das Endpunkt-Skript läuft
gar nicht erst an.

* '''Ohne den Header ändert sich nichts.''' Bestehende Endpunkte verhalten sich unverändert.
* '''Kein Schalter am Endpunkt.''' Die Mechanik greift automatisch, sobald der Header anliegt.
* '''Das Skript muss nichts tun.''' Eine eigene Idempotenz-Logik im Skript ist nicht mehr nötig.

Details und die Statuscodes: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Sitzungen und Abmelden==

Ein JWT trägt seine Gültigkeit in sich: der Server prüft Signatur und Ablauf und
braucht dafür keine Datenbank. Genau deshalb liesse sich ein ausgegebener Token
von sich aus auch nicht mehr zurückziehen - ein verlorenes Gerät wäre bis zum
Ablauf des Tokens weiter nutzbar.

Der Server führt deshalb zu jedem ausgestellten Token-Paar eine Zeile in
'''RESTSRV_TOKEN''' und prüft jeden Zugriff dagegen. Daraus ergeben sich drei
Eigenschaften:

* '''Abmelden wirkt sofort.''' Ein ''DELETE'' auf den JWT-Endpunkt sperrt die Sitzung; alle Token dieser Sitzung sind damit unmittelbar ungültig, auch die noch nicht abgelaufenen. Anmelden, Erneuern und Abmelden laufen also über einen einzigen Endpunkt, und für das Abmelden ist kein Skript nötig.
* '''Ein Refresh-Token gilt genau einmal.''' Beim Erneuern wird es entwertet. Wird es später erneut vorgelegt, gilt das als Diebstahl oder Fehlfunktion: die betroffene Sitzung wird komplett gesperrt und der Vorfall protokolliert.
* '''Alle Geräte abmelden.''' Ein gewöhnlicher Endpunkt kann über das Antwortfeld ''_OBS_JWT_REVOKE'' auch alle Sitzungen eines Benutzers sperren - der Support-Fall „Gerät verloren".

{{Achtung|Mit der Einführung dieser Prüfung verlieren '''alle vorher
ausgestellten Token''' ihre Gültigkeit, weil sie zu keiner Sitzung gehören.
Angemeldete Konsumenten müssen sich nach dem Update einmalig neu anmelden.}}

Der Speicher pflegt sich selbst: Zeilen werden gelöscht, sobald sowohl das
Access- als auch das Refresh-Token abgelaufen sind. Details und die Skript-Seite:
[[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Fehlerformat==

Jede Fehlerantwort des Servers hat dieselbe Form: ein einziges ''error''-Objekt
mit maschinenlesbarem Code, Support-Kennung, Meldung und Korrelations-ID:

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00E2RTPDY",
"message": "Ungültiges oder abgelaufenes Token",
"traceId": "20260817T091233123-00001A"
}
}
</pre>

* '''code''' - sprechender Bezeichner (z.B. ''AUTH_EXPIRED'', ''NOT_FOUND'', ''RATE_LIMITED'', ''INTERNAL_ERROR''), an dem ein Client seine Reaktion festmachen kann, ohne Texte auszuwerten.
* '''uid''' - OBS-Kennung der Codestelle. Für die Support-Recherche gedacht, nicht zur Auswertung im Client.
* '''message''' - Text für den Client. Interne Fehlerdetails stehen nie darin, sondern ausschliesslich im Protokoll '''RESTSRV_PROTO'''.
* '''traceId''' - Korrelations-ID. Steht zusätzlich im Header ''X-Trace-Id'' und in jeder zugehörigen Logzeile.

Ein Endpunkt-Skript kann eigene Codes setzen; siehe
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

{{Achtung|''Fehlercode'', ''Nachricht'' und ''traceId'' stehen '''nur''' im
''error''-Objekt, nicht flach daneben - der Wert von
''Fehlercode'' heisst jetzt ''error.uid'', ''Nachricht'' entspricht
''error.message''. Clients, die die flachen Felder auswerten, müssen angepasst
werden.}}

==Sicherheitsmerkmale==

Der REST-Server enthält eine Reihe von Schutzmechanismen:

* '''Rate-Limit:''' Standardmässig max. 10 fehlgeschlagene und 120 erfolgreiche Anfragen pro API-Key (Account) bzw. IP und 60 Sekunden, max. 600 Anfragen global pro 60 Sekunden. Beim Überschreiten wird HTTP 429 mit ''Retry-After''-Header zurückgegeben. Die vier Schwellen lassen sich '''pro Server-Profil''' hinterlegen; die Zähler laufen ebenfalls getrennt je Profil, ein überlastetes Profil bremst das andere also nicht mit aus. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].
* '''Body-Limit:''' max. 10 MB Request-Body (JSON), max. 1024 Zeichen pro Header- oder Query-Parameter. Datei-Uploads laufen über einen separaten Pfad und sind pro Endpunkt auf <code>re_upload_size</code> MB begrenzt (Standard 25 MB).
* '''Sensible Felder''' (''password'', ''token'', ''secret'', ''apikey'', ''authorization'', ''cookie'', ...) werden in Protokoll-Ausgaben automatisch maskiert.
* '''Widerrufbare Token:''' Jedes ausgestellte Token-Paar gehört zu einer Sitzung in '''RESTSRV_TOKEN''' und wird bei '''jedem''' Zugriff dagegen geprüft. Eine Abmeldung wirkt damit sofort und nicht erst mit dem Ablauf des Tokens; ein Refresh-Token gilt genau einmal. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].
* '''Reserviertes Präfix:''' Parameter-Namen mit Präfix ''_OBS_'' können von aussen nicht gesetzt werden, sie sind für den Server reserviert (z.B. JWT-Claims).
* '''Geblockte Header:''' ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key'' werden nicht an das Skript durchgereicht.
* '''TLS:''' Bei Profilen mit aktivem TLS fährt der Server ohne Zertifikat und Key nicht hoch. Plain-HTTP ist nur für ein dediziertes Debug-Profil möglich.
* '''mTLS''' (Mutual TLS): erzwingt, dass jeder Client ein gültiges Client-Zertifikat vorlegt. Optional kann pro Zugang ein erwarteter Subject-DN hinterlegt werden.
* '''DNS-Cache:''' Host-zu-IP-Auflösungen für die Zugangs-Host-Prüfung werden 5 Minuten gecached.

==Protokoll==

Die Tabelle '''RESTSRV_PROTO''' enthält alle relevanten Ereignisse: erfolgreiche und abgelehnte Anfragen, TLS-/JWT-Fehler, Bindungs-Ereignisse, Skript-Fehler. Einträge sind nach Datum, Uhrzeit und Host (IP oder Account-Name) sortiert. Das Protokoll ist die erste Anlaufstelle bei Störungen. Jede Antwort trägt zudem eine Korrelations-ID (Response-Header ''X-Trace-Id''), die in den Protokoll-Einträgen wiederzufinden ist.

==Statistik==

Die Tabelle '''RESTSRV_STATS''' enthält eine Statistik aller bearbeiteten Anfragen mit Zugang, Endpunkt, Methode, HTTP-Status und Laufzeit in Millisekunden. Aufruf der Statistik:

* Aus der Endpunkt-Liste: F8 zeigt die Statistik des markierten Endpunkts.
* Aus der Zugänge-Liste: F8 zeigt die Statistik des markierten Zugangs.

==Konsole==

Wird der REST-Server nicht als Dienst, sondern interaktiv gestartet, erscheint eine farbige Konsole mit Live-Log. Die wichtigsten Befehle:

{| class="wikitable"
! Befehl !! Wirkung
|-
| ''show <n>'' || Zeigt die Details zum Debug-Eintrag ''#n'' (z.B. Request-Header, Response-Body), JSON wird farbig formatiert
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Einträge landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]] - API-Keys, JWT, CORS, Host-Beschränkung
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]] - Dateien ausliefern, Range/Resume, öffentliche Artefakte
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

Vorlage:Kostenpflichtige Module

2026-09-09T12:33:27Z

Rademacker:

<div style="float:right; clear:both; margin-left:2px; padding:0px; background:#FFFFFF; width:19em">
<div style="border:none;margin-top:0pt;padding:0pt;" id="navigation">

<div style="position:relative;top:-20pt;color:#000000;background:#ffffff; border: 3pt double #cfcfcf; padding: 5pt; margin: 0pt;margin-bottom:-20pt; z-index:1;border-top-right-radius:7pt;-moz-border-radius-topright:7pt;-webkit-border-top-right-radius:7pt;border-bottom-left-radius:7pt;-moz-border-radius-bottomleft:7pt;-webkit-border-bottom-left-radius:7pt;box-shadow: 3px 3px 4px #c0c0c0;-webkit-box-shadow: 3px 3px 4px #c0c0c0;-moz-box-shadow: 3px 3px 4px #c0c0c0;">[[Hauptseite|Wiki]] » [[Kostenpflichtige Module|Kostenpflichtige Module]]</div>
</div>

{{Vorlage:Textbox-Blau|1=Kostenpflichtige Module|2=
<small>
{{Vorlage:Klapptext|kopf='''Internet-Shop'''|inhalt=
* [[OBS/Stammdaten/Schnittstellen/Internet-Shop| OBS Schnittstelle Internet Shop]]
{{Vorlage:Klapptext|kopf='''Der modified ECommerce Shop'''|inhalt=
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop-xtcModified/FAQs|FAQs]]
*[[OBS/Internet-Shop/modified-eCommerce|Überblick zum modified ECommerce Shop]]
{{Vorlage:Klapptext|kopf=Shop-Menü|inhalt=
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/A Preise aktualisieren|A Preise aktualisieren]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/C Personen übertragen|C Personen übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/E Kategorien verwalten|E Kategorien verwalten]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/G Kataloge verwalten|G Kataloge verwalten]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop-xtcModified/I Merkliste übertragen|I Merkliste übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/K Varianten übertragen|K Varianten übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/L Artikelvarianten übertragen|L Artikelvarianten übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/M Referenzarten übertragen|M Referenzarten übertragen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/N Lagerbestände verwalten|N Lagerbestände verwalten]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop#Bestellungen_einlesen|U Bestellungen einlesen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/V leere Passworte füllen|V leere Passworte füllen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/modified eCommerce/W Update-Informationen zurücksetzen|W Update-Informationen zurücksetzen]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop/Konfiguration/modified_eCommerce|X Konfiguration]]
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop#Protokoll|Z Protokoll]]
}}
{{Vorlage:Klapptext|kopf=Automatische Vorgänge|inhalt=
* [[OBS/Internet-Shop/modified-eCommerce/Scheduler/Bestellungen einlesen|Bestellungen einlesen]]
* [[OBS/Internet-Shop/modified-eCommerce/Scheduler/Verfügbarkeitsdateien erstellen|Verfügbarkeitsdateien erstellen]]
* [[OBS/Internet-Shop/modified-eCommerce/Scheduler/Verfügbarkeitsdateien hochladen|Verfügbarkeitsdateien hochladen]]
*[[OBS/Internet-Shop/modified-eCommerce/Scheduler/Änderungsautomatik|geänderte Artikel übertragen]]
*[[OBS/Internet-Shop/modified-eCommerce/Scheduler/Preise aktualisieren|Preise aktualisieren]]
*[[OBS/Internet-Shop/modified-eCommerce/Scheduler/Anlage Shopkategorien|Anlage der Shopkategorien auf Grundlage der OBS-Warengruppen]]
}}
*[[OBS/Stammdaten/Schnittstellen/Internet-Shop-xtcModified/besondere Funktionen|Besondere Anpassungen im xtcModified Shop]]<br>
}}

{{Vorlage:Klapptext|kopf=[[Kostenpflichtige_Module/Internet-Shop/modified_eCommerce_2|modified eCommerce 2.0]]|inhalt=
*[[OBS/Internet-Shop/modified_eCommerce_2.0|Funktionen und FAQ]]
}}

{{Vorlage:Klapptext|kopf=[[OBS/Internet-Shop/ShopV4|Der Büroring-ShopV4]]|inhalt=
*[[OBS/Internet-Shop/ShopV4/FAQs|FAQs]]
{{Vorlage:Klapptext|kopf=Einrichtung|inhalt=
* [[OBS/Internet-Shop/ShopV4/1.1_Einstellungen_im_Shop|Einstellungen im Shop]]
* [[OBS/Internet-Shop/ShopV4/1.2_Einstellungen_in_OBS|Einstellungen in OBS]]
* [[OBS/Internet-Shop/ShopV4/Erste_Schritte|Erste Schritte]]
}}
* [[OBS/Internet-Shop/ShopV4/Shop-Menu|Shop-Menü]]
* [[OBS/Internet-Shop/ShopV4/Shop-Lieferanten|Shop-Lieferanten]]
* [[OBS/Internet-Shop/ShopV4/Import_von_Bestellungen|Import von Bestellungen]]
* [[OBS/Internet-Shop/ShopV4/Personen_/_Kundengruppen|Personen / Kundengruppe]]
{{Vorlage:Klapptext|kopf=Eigene Artikel|inhalt=
* [[OBS/Internet-Shop/ShopV4/6.1_Artikel_übertragen|Artikel übertragen]]
* [[OBS/Internet-Shop/ShopV4/6.2_Shop-Warengruppen|Shop-Warengruppen]]
}}
* [[OBS/Internet-Shop/ShopV4/Preislisten|Preislisten]]
* [[OBS/Internet-Shop/ShopV4/Katalogvorlagen|Katalogvorlagen]]
* [[OBS/Internet-Shop/ShopV4/Bestellvorlagen|Bestellvorlagen]]
* [[OBS/Internet-Shop/ShopV4/Sortiment|Sortiment]]
* [[OBS/Internet-Shop/ShopV4/Kostenstellen|Kostenstellen]]
* [[OBS/Internet-Shop/ShopV4/Personen-Einstellungen|Personen-Einstellungen]]
}}

{{Vorlage:Klapptext|kopf=[[Kostenpflichtige_Module/Internet-Shop/brShop24|brShop24]]|inhalt=
* [[Kostenpflichtige_Module/Internet-Shop/brShop24|Übersicht]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Einrichtung|Einrichtung]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24#Bekannte_Probleme|Bekannte Probleme]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24#H.C3.A4ufig_gestellte_Fragen_.28FAQ.29|Häufig gestellte Fragen (FAQ)]]
{{Vorlage:Klapptext|kopf=[[Kostenpflichtige_Module/Internet-Shop/brShop24|Einstellungen und Automatiken]]|inhalt=
* [[OBS/Stammdaten/Schnittstellen/Internet-Shop/Konfiguration|Konfiguration]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24#Zuordnungen|Zuordnungen/Datenverknüpfung OBS und Shop]]
* [[Kostenpflichtige_Module/Internet-Shop/Einrichtung/Automatiken|Automatiken einrichten]]
}}
{{Vorlage:Klapptext|kopf=[[Kostenpflichtige_Module/Internet-Shop/brShop24#Erkl.C3.A4rungen.2FFunktionen|Funktionen]]|inhalt=
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Kundengruppen_verwalten|Kundengruppen verwalten]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Personen_übertragen|Personen übertragen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Preise_übertragen|Preise übertragen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Eigene_Artikel_übertragen|Eigene Artikel übertragen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Shoppinglisten_übertragen|Shoppinglisten übertragen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Jobinformationen|Jobinformationen]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Migration|Migration]]
* [[Kostenpflichtige Module/Internet-Shop/brShop24/PDF-Druck Artikellink|PDF-Druck Artikellink]]
* [[Kostenpflichtige_Module/Internet-Shop/brShop24/Definition_Sortiment|Definition Sortiment (individuelle Konfiguration)]]
}}
}}

* [[Kostenpflichtige Module/Internet-Shop/soCONNECT|so.CONNECT (Soennecken)]]

}}

{{Vorlage:Klapptext|kopf='''Preislisten'''|inhalt=
{{Vorlage:Klapptext|kopf=[[OBS/Kostenpflichtige_Module/Preislisten|Preislistenverwaltung]]|inhalt=
* [[OBS/Kostenpflichtige_Module/Preislisten/Preislisten-Artikel|Preislisten-Artikel]]
* [[OBS/Kostenpflichtige_Module/Preislisten/Preislistengruppen|Preislistengruppen]]
}}
* [[OBS/Preislisten/FAQ_Preislisten|FAQ Preislisten]]
* [[OBS/Häufig gestellte Fragen/Vorgehensweise für Preislisten ohne Server|Vorgehen für Preislisten ohne Server]]
* [[OBS/Häufig gestellte Fragen/Vorgehensweise mit Server/Client Installation für Preislisten|Vorgehen für Preislisten mit Server]]
{{Vorlage:Klapptext|kopf=[[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere Funktionen|F10 Weitere Funktionen]]|inhalt=
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Export_Import#A_Preisliste_nach_Excel|A Preisliste nach Excel]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Export_Import#B1_Excel_in_Preisliste|B1 Excel in Preisliste]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Export_Import#B2_freie_Excel_in_Preisliste|B2 freie Excel in Preisliste]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Export_Import#B3_Lieferanten-Preise_aus_CSV_in_Preisliste|B3 Lieferanten-Preise aus CSV in Preisliste]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/AutoPflege|C Automatische Vorgänge Preislisten]]
* [[OBS/Kostenpflichtige_Module/Preislisten/Formeln|D Formelverwaltung]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Angebot_Preisliste#F.C3.BCllen_einer_Preisliste_aus_Angebot|E1 Angebot nach Preisliste]]
* [[OBS/Stammdaten/Artikel/Preislistenverwaltung/Weitere_Funktionen/Angebot_Preisliste#Angebot_aus_Preisliste_generieren|E2 Preisliste nach Angebot]]
}}
{{Vorlage:Klapptext|kopf=[[OBS/Stammdaten/Artikel/Preislistenverwaltung/AutoPflege|Automatiken Kommandos]]|inhalt=
* [[OBS/Preislisten/Preislisten per Macro füllen|Preislisten per Macro füllen]]
* [[OBS/Preislisten/Preislisten per Macro kopieren|Preislisten per Macro kopieren]]
}}
}}

{{Vorlage:Klapptext|kopf='''ZUGFeRD'''|inhalt=
* [[OBS/Kostenpflichtige Module/ZUGFeRD|ZUGFeRD]]
* [[OBS/Kostenpflichtige Module/ZUGFeRD/Konfiguration|ZUGFeRD Konfiguration]]
}}
{{Vorlage:Klapptext|kopf='''Factoring'''|inhalt=
* [[OBS/Kostenpflichtige Module/Was ist Factoring?|Was ist Factoring?]]
* [[OBS/Kostenpflichtige Module/Factoring in OBS| Factoring in OBS]]
* [[OBS/Kostenpflichtige Module/Erstellen und Verwenden von Factoring Rechnungen|Erstellen und Verwenden von Factoring Rechnungen]]
* [[OBS/Kostenpflichtige Module/Auswertung und Übermittlung von Factoring Rechnungen|Auswertung und Übermittlung von Factoring Rechnungen]]
* [[OBS/Kostenpflichtige Module/Factoring Fibu|Factoring Fibu]]
}}
{{Vorlage:Klapptext|kopf='''UPS'''|inhalt=
* [[OBS/kostenpflichtige Module/UPS|UPS Modul]]
}}
{{Vorlage:Klapptext|kopf='''DHL'''|inhalt=
* [[OBS/kostenpflichtige Module/DHL|DHL Schnittstelle]]
}}
{{Vorlage:Klapptext|kopf='''IMS Professional'''|inhalt=
;
* [[OBS/kostenpflichtige Module/IMSPro|IMS-Professional]]

}}
{{Vorlage:Klapptext|kopf='''TAPI'''|inhalt=
* [[OBS/Kostenpflichtige Module/TAPI|TAPI]]
* [[OBS/Kostenpflichtige Module/TAPI Voraussetzungen|Voraussetzungen]]
* [[OBS/Kostenpflichtige Module/TAPI Konfiguration|Konfiguration]]
* [[OBS/Kostenpflichtige Module/TAPI Externe Telefonanbindungen|Externe Telefonanbindungen]]
}}
{{Vorlage:Klapptext|kopf='''SMS'''|inhalt=
* [[OBS/Kostenpflichtige Module/SMS|SMS]]
}}
{{Vorlage:Klapptext|kopf=[[OBS/Kostenpflichtige_Module/Fleet_Management|'''Fleet Management''']]|inhalt=
* [[OBS/Kostenpflichtige Module/Fleet Management/FMAudit|FMAudit]]
* [[FRMFMZENTRALE_MELDUNGEN|FMAudit Pro]]
* [[OBS/Kostenpflichtige Module/Fleet Management/UTAX E-mail|UTAX E-Mail]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/Brother_XML|Brother XML]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/KonicaMinolta_E-Mail|Konica Minolta E-Mail]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/docuFORM|docuFORM XML]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/KyoceraFleetServices|KFS XML]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/SimpleClicksXML|SimpleClicks XML]]
* [[OBS/Kostenpflichtige_Module/Fleet_Management/Brother_PPPB_xlsx|Brother PPPB Xlsx]]
}}
{{Vorlage:Klapptext|kopf='''Mehrlager-Verwaltung'''|inhalt=
* [[OBS/Kostenpflichtige Module/Mehrlager-Verwaltung|Mehrlager-Verwaltung]]
}}
{{Vorlage:Klapptext|kopf='''Mehrsprachen Modul'''|inhalt=
* [[OBS/Kostenpflichtige Module/Mehrsprachen Modul|Mehrsprachen Modul]]
}}
{{Vorlage:Klapptext|kopf='''Multilanguage Modul'''|inhalt=
* [[OBS/Kostenpflichtige Module/Multilanguage Modul|Multilanguage Modul]]
}}

{{Vorlage:Klapptext|kopf='''Einfache Produktionsnachverfolgung'''|inhalt=
* [[OBS/Einfache Produktionsnachverfolgung/Was ist|Was ist die Einfache Produktionsnachverfolgung]]
* [[OBS/Einfache Produktionsnachverfolgung/FRMEDITPRODMENGE|Scannen der Auftragspositionen]]
* [[OBS/Einfache Produktionsnachverfolgung/Sammellieferschein|Sammellieferschein]]
}}
{{Vorlage:Klapptext|kopf='''DMS - Dokumenten Management System'''|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS|DMS]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Konfiguration|Konfiguration]]
* [[OBS/Kostenpflichtige Module/DMS/Scannen von Dokumenten|Einscannen von Dokumenten im Stapelbetrieb]]
{{Vorlage:Klapptext|kopf=DMS Dokumente|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente|Liste]]
* [[OBS/Kostenpflichtige Module/DMS/Versionierung|Dokumentenversionierung]]
{{Vorlage:Klapptext|kopf=Tasten und Schaltflächen|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F2 Filter|F2 Filter]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F5 Markieren|F5 Mark]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Verknüpfung|F6 Verknü.]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F7 Suche|F7 Suche]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F8 Info|F8 Info]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F9 Gruppe|F9 Gruppe]]
{{Vorlage:Klapptext|kopf=F10 Weit.|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS Dokumente/F10 Weitere Funktionen|F10 Weit.]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Stammdaten|DMS Stammdaten]]
{{Vorlage:Klapptext|kopf=E DMS Definitionen|inhalt=
* [[OBS/Kostenpflichtige Module/DMS/DMS Definitionen|Liste]]
* [[OBS/Kostenpflichtige Module/DMS/DMS Definitionen Eingabemaske|Eingabemaske]]
}}
* [[OBS/Kostenpflichtige Module/DMS/QR Etiketten|M QR Etiketten drucken]]
}}
* [[OBS/Kostenpflichtige Module/DMS/DMS Viewer|Dokument]]
}}
* [[OBS/Kostenpflichtige Module/DMS/DMS Eingabemaske|Eingabemaske]]
}}
}}

{{Vorlage:Klapptext|kopf='''QR Zeiterfassung'''|inhalt=
* [[OBS/Kostenpflichtige Module/QR Zeiterfassung|QR Zeiterfassung]]
* [[OBS/Kostenpflichtige Module/QR Einrichtung Checkliste|QR Einrichtung Checkliste]]
}}

{{Vorlage:Klapptext|kopf='''EVA Marketing Tool'''|inhalt=
* [[OBS/EVA]]
}}

{{Vorlage:Klapptext|kopf='''Technikersteuerung'''|inhalt=
* [[OBS/Kostenpflichtige Module/Technikersteuerung/Ziel der Technikersteuerung|Ziel der Technikersteuerung]]
* [[OBS/Kostenpflichtige Module/Technikersteuerung/Konfiguration|Konfiguration]]
* [[OBS/Kostenpflichtige Module/Technikersteuerung/Terminvorschläge erstellen|Terminvorschläge für Techniker erstellen]]
* [[OBS/Kostenpflichtige Module/Technikersteuerung/Liste|Liste]]
** [[OBS/Kostenpflichtige Module/Technikersteuerung/Definition Terminvorschlagslisten|Definition Terminvorschlagslisten/T-Def]]
** [[OBS/Kostenpflichtige Module/Technikersteuerung/Terminvorschläge bearbeiten|Terminvorschläge für Techniker bearbeiten]]
** [[OBS/Kostenpflichtige Module/Technikersteuerung/Terminvorschlagsliste aktualisieren|Terminvorschlagsliste akt./T-Liste]]
}}

{{Vorlage:Klapptext|kopf='''Termin-Projekte'''|inhalt=
* [[OBS/Kostenpflichtige Module/Termin-Projekte|Termin-Projekte]]
}}

{{Vorlage:Klapptext|kopf='''Edifact-Schnittstelle'''|inhalt=
* [[OBS/Kostenpflichtige Module/Edifact|Edifact Schnittstelle]]
}}

{{Vorlage:Klapptext|kopf='''Backup Überwachung Email'''|inhalt=
* [[OBS/Kostenpflichtige Module/Backup Überwachung Email|Backup Überwachung Email]]
}}

{{Vorlage:Klapptext|kopf='''Anlagenbuchhaltung'''|inhalt=
* [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung|Anlagenbuchhaltung]]
** [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Auswertungen|Auswertungsdrucke]]
** [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Anlagengüter|Anlagegüterübersicht]]
** [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Abschreibungsarten|Abschreibungsarten]]
* [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Anlagekonten|Anlagekonten]]
* [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Bewegung|Anlagebewegungen]]
* [[OBS/Kostenpflichtige Module/Anlagenbuchhaltung/Anlagenstapel|Anlagenstapel]]
}}

{{Vorlage:Klapptext|kopf='''OBS Geo Daten'''|inhalt=
* [[OBS/Kostenpflichtige Module/OBS Geo Daten|OBS Geo Daten]]
}}

{{Vorlage:Klapptext|kopf='''DeliSprint / DPD'''|inhalt=
* [[OBS/Kostenpflichtige_Module/Delisprint|DeliSprint / DPD]]
}}

{{Vorlage:Klapptext|kopf='''Filialen'''|inhalt=
* [[OBS/Kostenpflichtige Module/Filialen|Filialen]]
}}

{{Vorlage:Klapptext|kopf='''Auto-Waagen'''|inhalt=
* [[OBS/Kostenpflichtige Module/Auto-Waagen|Auto-Waagen]]
* [[OBS/Kostenpflichtige Module/Auto-Waagen/Installation|Installation]]
* [[OBS/Kostenpflichtige Module/Auto-Waagen/Liste|Liste]]
* [[OBS/Kostenpflichtige Module/Auto-Waagen/Eingabemaske|Eingabemaske]]
* [[OBS/Kostenpflichtige Module/Auto-Waagen/Waage.INI|Waage.INI]]
}}

{{Vorlage:Klapptext|kopf='''Cashback'''|inhalt=
* [[OBS/Kostenpflichtige Module/Cashback|Cashback]]
}}
{{Vorlage:Klapptext|kopf='''Moebelschnittstelle'''|inhalt=
*[[OBS/Kostenpflichtige Module/Moebelschnittstelle|Moebelschnittstelle]]
}}
{{Vorlage:Klapptext|kopf='''Tourenplanung'''|inhalt=
{{Vorlage:Klapptext|kopf=[[OBS/Kostenpflichtige Module/Tourenplanung|Tourenplanung]]|inhalt=
*[[OBS/Kostenpflichtige Module/Tourenplanung/TourVG|Vorgänge]]
*[[OBS/Kostenpflichtige Module/Tourenplanung/TourTouren|Touren]]
*[[OBS/Kostenpflichtige Module/Tourenplanung/TourTourPos|Positionen]]
}}
*[[OBS/Kostenpflichtige Module/Tourenplanung/Stammdaten|Stammdaten]]
*[[OBS/Kostenpflichtige Module/Tourenplanung/Einrichtung|Einrichtung]]
}}
{{Vorlage:Klapptext|kopf='''Dokumenten Manager'''|inhalt=
*[[OBS/Kostenpflichtige_Module/Dokumenten_Manager|Dokumenten Manager]]
}}
{{Vorlage:Klapptext|kopf='''DocuWare-Schnittstelle'''|inhalt=
*[[OBS/Kostenpflichtige_Module/DocuWare|DocuWare-Schnittstelle]]
}}
{{Vorlage:Klapptext|kopf='''OFML-Kalkulation'''|inhalt=
*[[OBS/Kostenpflichtige_Module/OFML-Kalkulation|OFML-Kalkulation]]
}}
{{Vorlage:Klapptext|kopf='''Pascom'''|inhalt=
*[[OBS/Kostenpflichtige_Module/Pascom|Pascom]]
*[[OBS/Kostenpflichtige_Module/Pascom_Einrichtung|Einrichtung]]
}}
{{Vorlage:Klapptext|kopf='''Versicherungsschaden'''|inhalt=
*[[OBS/Kostenpflichtige_Module/Versicherungsschaden|Versicherungsschaden]]
*[[OBS/Kostenpflichtige_Module/Energienachweise|Energienachweise]]
}}
{{Vorlage:Klapptext|kopf='''Gutschriftsanzeigen'''|inhalt=
* [[OBS/Kostenpflichtige Module/Gutschriftsanzeigen|Gutschriftsanzeigen]]
}}
{{Vorlage:Klapptext|kopf='''OCPP Ladestationen'''|inhalt=
* [[OBS/Kostenpflichtige Module/OCPP_Ladestationen|OCPP Wallboxen Abrechnung (Ladesäulen)]]
* [[OBS/Kostenpflichtige Module/SteVe|SteVe]]
}}
{{Vorlage:Klapptext|kopf='''Kameraverwaltung'''|inhalt=
* [[OBS/Kostenpflichtige Module/Kameraverwaltung|Kameraverwaltung]]
}}
{{Vorlage:Klapptext|kopf='''DataInOut'''|inhalt=
* [[OBS/Kostenpflichtige Module/DataInOut|DataInOut]]
}}
{{Vorlage:Klapptext|kopf='''REST-Schnittstelle'''|inhalt=
* [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]]
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Skripting]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
{{Vorlage:Klapptext|kopf='''Beispiele'''|inhalt=
*[[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|PHP-Abruf von Steuerungsdaten]]
*[[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Zeiterfassung]]
*[[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Externes Ticketsystem]]
*[[OBS/Kostenpflichtige_Module/RESTServer/Beispiel4|Pfad-Parameter]]
*[[OBS/Kostenpflichtige_Module/RESTServer/Beispiel5|Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
*[[OBS/Kostenpflichtige_Module/RESTServer/Beispiel6|Datei-Upload und Ablage im DMS]]
}}
}}

{{Vorlage:Klapptext|kopf='''Sammelverträge'''|inhalt=
* [[OBS/Kostenpflichtige Module/Sammelvertrag|Sammelvertrag]]
* [[OBS/Kostenpflichtige Module/Sammelvertrag/Container|Container-Stammdaten]]
}}

{{Vorlage:Klapptext|kopf='''Craftboxx'''|inhalt=
* [[OBS/Kostenpflichtige Module/Craftboxx|Craftboxx]]
* [[OBS/Kostenpflichtige Module/CraftboxxAPI|Craftboxx API Dokumentation]]
}}

{{Vorlage:Klapptext|kopf='''OpenMasterData / IDS'''|inhalt=
* [[OBS/Kostenpflichtige Module/OpenMasterData|OpenMasterData]]
* [[BS/Kostenpflichtige Module/IDSConnect|IDSConnect]]
}}

{{Vorlage:Klapptext|kopf='''Sammelpositionen'''|inhalt=
* [[OBS/Kostenpflichtige Module/Sammelpositionen|Sammelpositionen]]
}}

{{Vorlage:Klapptext|kopf='''KI-Mining'''|inhalt=
* [[OBS/Kostenpflichtige Module/KI-Mining|KI-Mining]]
{{Vorlage:Klapptext|kopf=KI-Mining Apps|inhalt=
* [[OBS/Kostenpflichtige Module/KI-Mining/Auftragsmonitor|Auftragsmonitor]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Lageroptimierung|Lageroptimierung]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Kundenklassifizierung|Kundenklassifizierung]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Cross-Selling|Cross-Selling]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Vertriebs-ToDos|Vertriebs-ToDos]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Vertriebs-ToDos pro|Vertriebs-ToDos pro]]
* [[OBS/Kostenpflichtige Module/KI-Mining/MPS-ToDos pro|MPS-ToDos pro]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Vertriebs-Wirkungsmonitor|Vertriebs-Wirkungsmonitor]]
* [[OBS/Kostenpflichtige Module/KI-Mining/Führungs-Dashboard|Führungs-Dashboard]]
}}
}}

</small>
}}

</div>

<noinclude>
----
</noinclude>

<noinclude>

Folgender Code muss in die jeweils gewünschte Seite hinzugefügt werden:
<nowiki>{{Kostenpflichtige Module}}</nowiki>
[[Kategorie:Templates/Navigationen]]
</noinclude>
[[Kategorie:OBS/Module]]

OBS/Kostenpflichtige Module/RESTServer/Datei-Upload

2026-09-09T12:32:35Z

Rademacker: Die Seite wurde neu angelegt: „{{Kostenpflichtige Module}} = Datei-Upload = Ein Endpunkt nimmt Dateien nur entgegen, wenn er dafür freigeschaltet ist (<code>re_upload = 1</code>, siehe Endpunkte). Dann gilt nicht das JSON-Body-Limit von 10 MB, sondern die pro Endpunkt konfigurierte Grösse (<code>re_upload_size</code>, Standard 25 MB; Überschreitung -> '''413'''). Diese Seite beschreibt die '''Übertragung''' - was ein…“

OBS/Kostenpflichtige Module/RESTServer/Beispiel1

2026-09-09T12:32:15Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 1: Daten-Abruf mit JWT-Authentifizierung=

In diesem Beispiel werden Steuerungs-Variablen aus OBS abgerufen und auf einer Webseite ausgegeben. Der Zugang ist mit JWT-Pflicht eingerichtet, der Konsument muss sich daher zuerst anmelden und einen Token bezogen haben.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' mit Bindung 0.0.0.0:443
* '''Zugang:''' ''Web-Dashboard''
** API-Key: zufaellig generiert
** JWT aktiv, JWT-Endpunkt ''oauth'', JWT-Key zufaellig, JWT-Exp 60 (Minuten)
** CORS-Origins: ''https://dashboard.kunde.de''
* '''Endpunkt:''' ''steuerung/v1'', dem Profil ''Public-API'' zugeordnet
* '''Berechtigung:''' Zugang ''Web-Dashboard'' fuer Endpunkt ''steuerung/v1'' freigeschaltet

==JWT-Authentifizierungs-Skript (Zugang)==

Wird ueber die Zugaenge-Liste mit '''F7''' geoeffnet. Pruefen, ob Benutzername/Passwort gegen die OBS-Benutzerverwaltung passen.

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser : string;
cPass : string;
cSql : string;
qUser : TxFQuery;
lOk : Boolean;
begin
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

cSql := 'SELECT u_nr, u_name FROM benutzer' +
' WHERE u_login = ' + DB_SQLVal(cUser) +
' AND u_passwort_hash = ' + DB_SQLVal(HashPasswort(cPass)) +
' AND u_aktiv = ' + DB_SQLVal('1');

// DB_SOpen liefert true, wenn die ABFRAGE lief - nicht, wenn ein
// Datensatz gefunden wurde. Ohne die EoF-Pruefung wuerde jede
// Anmeldung gelingen, sobald das SQL fehlerfrei ist.
lOk := false;
if (DB_SOpen(oDB, cSql, qUser)) then begin
if (not qUser.EoF) then begin
lOk := true;
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , qUser.A2C('u_nr'));
oWriter.Str('_OBS_JWT_SUBJECT' , qUser.A2C('u_name'));
oWriter.Str('_OBS_JWT_AUDIENCE', 'dashboard');
end;
end;
DB_Close(qUser);

if (not lOk) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Benutzer oder Passwort ist falsch');
end;
end;
</syntaxhighlight>

{{Hinweis|Hier steht in ''_OBS_JWT_ID'' die Benutzernummer - derselbe Wert also bei
jeder Anmeldung desselben Benutzers. Das ist zulässig: der Server führt seine
Sitzungen über eigene Kennungen (''sid''/''rid''), nicht über das ''jti'' des
Skripts. Mehrfache und parallele Anmeldungen eines Benutzers sind damit
unproblematisch.}}

==Endpunkt-Skript ''steuerung/v1''==

Liefert eine Liste von Steuerungs-Werten zurueck. Die Auswertung der JWT-Claims sorgt dafuer, dass nur Audience ''dashboard'' Daten erhaelt.

<syntaxhighlight lang="pascal" line>
//------------------------------------------------------------------------------
// Ein Wert als Listeneintrag. Der Helfer bekommt den WRITER und schreibt an
// der Stelle hinein, an der er aufgerufen wird - er gibt kein Fragment zurueck.
// Der leere Feldname ist der Eintrag einer Liste.
//------------------------------------------------------------------------------

procedure _AddVar(oWriter: TxRestWriter; const cVar: string);
var cTitel : string;
cData : string;
cEinh : string;
lString: Boolean;
lAlign : Boolean;
begin
if (ST_Variable(oDB, cVar, cTitel, cData, cEinh, lString, lAlign)) then begin
oWriter.ObjBegin('');
oWriter.Str('variable', cVar);
oWriter.Str('titel' , cTitel);
oWriter.Str('wert' , cData);
oWriter.Str('einheit' , cEinh);
oWriter.ObjEnd;
end;
end;

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// Audience-Pruefung: nur Dashboard-Tokens akzeptieren. Die Ablehnung ist
// ein 403 und keine 200 mit Fehlertext - oWriter.Error baut dieselbe
// Huelle, die auch die Server-eigenen Fehler tragen.
if (oReader.Param('_OBS_JWT_AUDIENCE') <> 'dashboard') then begin
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Token nicht für diese Anwendung ausgestellt');
exit;
end;

// Die Antwort ist eine nackte Liste, kein Objekt: RootArr sagt das, und
// zwar VOR dem ersten Eintrag. Ein ArrEnd gibt es dazu nicht - die
// Wurzelklammer setzt der Server.
oWriter.RootArr();
_AddVar(oWriter, 'WERT_1');
_AddVar(oWriter, 'WERT_2');
_AddVar(oWriter, 'WERT_3');
_AddVar(oWriter, 'WERT_4');
end;
</syntaxhighlight>

==JavaScript-Client (Browser)==

Im Browser werden zwei Aufrufe gemacht: erst Token holen, dann Daten lesen.

<syntaxhighlight lang="javascript" line>
const API_BASE = 'https://api.meinserver.de';
const API_KEY = '[API-KEY]';

async function login(username, password) {
const res = await fetch(`${API_BASE}/oauth/`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'apikey': API_KEY },
body: JSON.stringify({ username, password })
});
if (!res.ok) throw new Error('Login fehlgeschlagen');
const data = await res.json();
return data.token;
}

async function ladeSteuerung(token) {
const res = await fetch(`${API_BASE}/steuerung/v1`, {
method: 'GET',
headers: {
'apikey': API_KEY,
'Authorization': 'Bearer ' + token
}
});
if (!res.ok) throw new Error('Abruf fehlgeschlagen: ' + res.status);
return res.json();
}

async function zeigeTabelle() {
const token = await login('mitarbeiter', 'geheim');
const werte = await ladeSteuerung(token);

const tbl = document.getElementById('steuerung');
werte.forEach(w => {
const tr = document.createElement('tr');
tr.innerHTML = `<td>${w.titel}</td><td>${w.wert} ${w.einheit}</td>`;
tbl.appendChild(tr);
});
}

zeigeTabelle();
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"mitarbeiter\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/oauth/

Antwort:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 3600,
"serverTime": "2026-08-19T09:12:33+02:00"}

Da das Skript kein ''_OBS_JWT_REFRESH_ID'' liefert, enthält die Antwort kein
''refreshToken'' - der Client meldet sich nach Ablauf der 60 Minuten neu an.

Daten abrufen:

curl -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJhbGciOi..." ^
https://api.meinserver.de/steuerung/v1

==Was zeigt das Beispiel?==

* Zweistufige Anmeldung: API-Key + JWT.
* Sichere Trennung von Konsumenten-Gruppen ueber die Audience-Claim.
* Eigenes Authentifizierungs-Skript pro Zugang.
* Browser-Zugriff ueber CORS-erlaubtes Origin.
* Anmeldung ohne Refresh-Token: einfachster Fall, der Token laeuft nach der Zeit aus ''JWT-Exp'' ab.

OBS/Kostenpflichtige Module/RESTServer/Beispiel6

2026-09-09T12:32:06Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 6: Datei-Upload und Ablage=

Dieses Beispiel zeigt einen Endpunkt, der '''Dateien entgegennimmt''': Ein
Aussendienst-Mitarbeiter fotografiert vor Ort ein Gerät, die App lädt das Foto zum
Auftrag hoch, der Server legt es ab und verknüpft es mit dem Vorgang.

Der Ablauf ist derselbe für Belege aus einem Scanner, Unterschriften-Bilder oder
Prüfprotokolle als PDF. Behandelt werden beide Übertragungsarten - der einfache
Upload für kleine Dateien und der fortsetzbare Upload für grosse.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App'', API-Key zufällig generiert, JWT aktiv
* '''Endpunkt:''' ''/orders/{uid}/photos'', Profil ''Public-API''
** '''Datei-Upload''' auf '''Ja''' setzen (<code>re_upload = 1</code>)
** '''Max. Upload-Grösse''' auf ''20'' (MB) setzen
* '''Berechtigung:''' Zugang ''Mobile-App'' für den Endpunkt freischalten

{{Hinweis|Ohne den Haken '''Datei-Upload''' lehnt der Server jeden Upload mit
'''415''' ab und das Skript läuft gar nicht erst an. Das ist die häufigste Ursache,
wenn ein Upload "ohne erkennbaren Grund" scheitert.}}

==Was der Server erledigt, bevor das Skript läuft==

Der Server nimmt die Datei entgegen, prüft die Grösse, legt sie in einem temporären
Verzeichnis ab und übergibt dem Skript drei Parameter:

{| class="wikitable"
! Aufruf !! Inhalt
|-
| <code>oReader.UploadPath()</code> || Vollständiger Pfad zur temporären Datei
|-
| <code>oReader.UploadName()</code> || Originaldateiname, wie ihn der Client gesendet hat
|-
| <code>oReader.UploadType()</code> || Content-Type der Datei
|-
| <code>oReader.UploadSha()</code> || SHA-256 der gespeicherten Datei (hex, klein)
|}

Zwei Dinge sind beim Schreiben des Skripts wichtig:

* '''Bei Uploads gibt es keinen JSON-Körper''' - <code>oReader.HasBody()</code> ist <code>false</code>, der Request-Body ist die Datei. Zusatzangaben (Kategorie, Bemerkung) kommen deshalb als '''Query-Parameter''' mit - oder, bei <code>multipart/form-data</code>, als weitere '''Formularfelder''', lesbar über <code>oReader.Form('<name>')</code>.
* '''Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt.''' Der Server räumt sie nicht selbst weg.

==Endpunkt-Skript ''/orders/{uid}/photos''==

Das Skript prüft den Dateityp, baut einen Zielpfad aus Auftrag und Zeitstempel,
verschiebt die Datei dorthin und schreibt einen Verweis in die Datenbank.

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
const ZIEL_BASIS = 'D:\OBS\Daten\Auftragsfotos\';
var cUid : string;
cTmpPfad : string;
cOrigName : string;
cTyp : string;
cEndung : string;
cKategorie: string;
cZielDir : string;
cZielName : string;
cZielPfad : string;
qNeu : TqSQL;
begin
cUid := oReader.Path('uid');
cTmpPfad := oReader.UploadPath();
cOrigName := oReader.UploadName();
cTyp := oReader.UploadType();
cKategorie := oReader.Param('kategorie'); // Query-Parameter, nicht Body

// 1) Gehoert der Auftrag zum Mandanten aus dem Token?
if (not AuftragGehoertZuMandant(oReader.Claim('tenant'), cUid)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
exit;
end;

// 2) Dateityp gegen eine Whitelist pruefen - niemals gegen eine
// Blacklist, und niemals dem Content-Type allein vertrauen.
cEndung := Lower(ExtractFileExt(cOrigName));
if ((cEndung <> '.jpg') and (cEndung <> '.jpeg') and (cEndung <> '.png') and (cEndung <> '.pdf')) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Nur JPG, PNG und PDF sind zulässig');
exit;
end;

// 3) Zielname selbst bilden. Den Originalnamen NICHT als Pfad
// verwenden - er kommt vom Client und kann '..\' enthalten.
cZielDir := ZIEL_BASIS + DToS(Date()) + '\' + cUid + '\';
cZielName := DToSF(Now()) + '_' + GlobalUID() + cEndung;
cZielPfad := cZielDir + cZielName;

MyForceDirectories(cZielDir);

if (not FMove(cTmpPfad, cZielPfad)) then begin
// Fehlgeschlagenes Verschieben ist ein Serverproblem -> 500.
// Der Idempotency-Key wird bei 5xx wieder freigegeben, der
// Client darf denselben Schluessel erneut senden.
oWriter.Error(500, 'INTERNAL_ERROR', 'Datei konnte nicht abgelegt werden');
exit;
end;

// 4) Verweis in der Datenbank ablegen
qNeu := qSqlInit(oDB, 'AUFTRAG_DOKUMENT');
qNeu.qSet('ad_auftrag' , cUid);
qNeu.qSet('ad_pfad' , cZielPfad);
qNeu.qSet('ad_dateiname', cOrigName);
qNeu.qSet('ad_typ' , cTyp);
qNeu.qSet('ad_kategorie', cKategorie);
qNeu.qSet('ad_datum' , Now());
// Rueckgabewert auswerten: ohne das bestaetigt der Endpunkt eine
// Ablage, die es nicht gibt - die Datei liegt dann im Zielverzeichnis,
// aber ohne Verweis in der Datenbank.
if (not qNeu.SaveData(NEW_RECORD)) then begin
qSqlFree(qNeu);
oWriter.Error(500, 'INTERNAL_ERROR', 'Verweis konnte nicht gespeichert werden');
exit;
end;
qSqlFree(qNeu);

// 5) 201 mit Location auf die abgelegte Datei
oWriter.Str('dateiname', cZielName);
oWriter.Int('groesse' , FSize(cZielPfad));
oWriter.Status(201);
oWriter.Header('Location', '/orders/' + cUid + '/photos/' + cZielName);
end;
</syntaxhighlight>

{{Hinweis|Soll die Datei statt in ein Verzeichnis in das '''OBS-Dokumenten-System'''
wandern, ersetzt der DMS-Aufruf die Schritte 3 bis 5. Welche Funktion dafür
zuständig ist, hängt vom eingesetzten Dokumenttyp ab - bitte mit dem OBS-Support
klären.}}

{{Hinweis|'''Fünf Fehlerausgänge, fünf Zeilen.''' Vorher baute jeder von ihnen
sein ''error''-Objekt, seinen Statuscode und seine ''traceId'' von Hand - fünfmal
dasselbe Muster, das an einer Stelle abweichen kann, ohne dass es auffällt.
<code>oWriter.Error</code> setzt alles davon, auch die ''traceId'', und verwirft
einen bereits begonnenen Körper. Ein ''exit'' danach genügt.}}

==Test mit curl==

Einfacher Upload einer Datei (''-F'' erzeugt ''multipart/form-data''):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-F "datei=@C:\Fotos\geraet.jpg" ^
"https://api.meinserver.de/orders/4711/photos?kategorie=VORHER"

Antwort:

HTTP/1.1 201 Created
Location: /orders/4711/photos/20260817091233_A1B2C3.jpg
X-Trace-Id: 20260817T091233123-00001A

{"dateiname":"20260817091233_A1B2C3.jpg","groesse":248113}

Ein Upload an einen Endpunkt '''ohne''' Upload-Freigabe:

HTTP/1.1 415 Unsupported Media Type

Eine Datei über der eingestellten Grenze:

HTTP/1.1 413 Payload Too Large

==Grosse Dateien: fortsetzbarer Upload==

Bei einem Foto aus dem Mobilfunknetz reisst die Verbindung schnell einmal ab. Für
solche Fälle überträgt der Client die Datei in Teilstücken und kann nach einem
Abbruch dort weitermachen, wo er aufgehört hat. '''Am Endpunkt-Skript ändert sich
dafür nichts''' - der Server sammelt die Teilstücke selbst ein und ruft das Skript
erst auf, wenn die Datei vollständig ist.

Der erste Teil trägt den Dateinamen (Base64-kodiert im Header
<code>Upload-Metadata</code>) und liefert eine <code>Upload-Id</code> zurück:

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Content-Range: bytes 0-1048575/5000000" ^
-H "Upload-Metadata: filename Z2VyYWV0LmpwZw==,filetype aW1hZ2UvanBlZw==" ^
--data-binary "@teil1.bin" ^
https://api.meinserver.de/orders/4711/photos

HTTP/1.1 308 Resume Incomplete
Upload-Id: 7f2a9c84...
Upload-Offset: 1048576
Range: bytes=0-1048575

Jeder weitere Teil sendet die ''Upload-Id'' mit. Der letzte Teil bekommt die
normale Antwort des Skripts (hier '''201'''). Nach einem Abbruch fragt der Client
den Stand ab und setzt dort auf:

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Content-Range: bytes */5000000" -H "Upload-Id: 7f2a9c84..." ^
https://api.meinserver.de/orders/4711/photos

HTTP/1.1 308 Resume Incomplete
Upload-Offset: 3145728

{{Hinweis|Der Zwischenstand liegt im Arbeitsspeicher des Dienstes. Wird der
REST-Dienst neu gestartet, muss ein unvollständiger Upload von vorn beginnen.}}

==Doppelte Uploads vermeiden==

Bricht die Verbindung ab, nachdem der Server die Datei schon abgelegt hat, würde ein
Wiederholversuch dasselbe Foto ein zweites Mal einliefern. Dagegen sendet der Client
den Header <code>Idempotency-Key</code> - für jedes Foto einen eigenen, über alle
Wiederholversuche hinweg denselben:

-H "Idempotency-Key: foto-4711-0003"

Der Server erkennt die Wiederholung und liefert die '''gespeicherte 201-Antwort'''
samt Header <code>Idempotent-Replay: true</code> zurück, ohne das Skript erneut zu
starten. Es entsteht also weder eine zweite Datei noch ein zweiter DB-Eintrag.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz.

==Was zeigt das Beispiel?==

* Endpunkt mit '''Datei-Upload-Freigabe''' (<code>re_upload</code>) und eigener Grössenbegrenzung.
* Zugriff auf die hochgeladene Datei über ''oReader.UploadPath()'', ''UploadName()'' und ''UploadType()''.
* Zusatzangaben als '''Query-Parameter''' oder Formularfeld, weil bei Uploads kein JSON-Körper vorliegt.
* '''Whitelist''' für zulässige Dateitypen und ein '''selbst gebildeter Zielname''' - der Originalname landet nie im Pfad.
* Übernahme der temporären Datei mit ''FMove''; ohne diesen Schritt bleibt sie liegen.
* Antwort mit '''201''' und ''Location''-Header.
* Fortsetzbarer Upload ohne jede Änderung am Skript.
* Schutz gegen doppelte Einlieferung über den ''Idempotency-Key''.

==Siehe auch==

* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Upload-Parameter und Protokoll im Detail
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Freigabe, Grössenlimit, Idempotenz
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5]] - Schreibzugriff mit Statuscodes und ETag

OBS/Kostenpflichtige Module/RESTServer/Beispiel2

2026-09-09T12:31:56Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 2: Zeiterfassung als komplette Webanwendung=

Dieses Script dient zur Zeiterfassung über den REST-Server. Bei Seitenaufruf wird eine Liste von Kunden geladen und in einer Liste angezeigt.

Durch Rechtsklick auf einen Eintrag wird eine Liste an zugehörigen Tätigkeiten geladen, die nach Klick einen Timer starten.

Per Javascript werden Startzeit, Startdatum und andere Informationen wie Kunde und Personalnummer über die PHP-Scripte und das Endpunkt-Script in einer Datenbank gespeichert.

Der Status wird hierbei auf "1" gesetzt. Pausenzeiten werden nach Beenden einer Pause in der Datenbank gespeichert.

Durch Drücken des Stop-Buttons wird eine Lightbox mit einer Zusammenfassung aller zum Timer gehörenden Daten angezeigt. Hier hat man die Möglichkeit Tätigkeiten, abgelaufene Zeit und

Pausenzeit nachträglich zu bearbeiten. Durch Klick auf "Speichern" oder Druck auf F2 werden Endzeit und Enddatum gespeichert und der Status auf "21" gesetzt.

Nach Reload der Webseite wird anhand des Status in der Datenbank nach laufenden Timern gesucht und diese gegebenenfalls gestartet.

= Endpunkt-Script =
<syntaxhighlight lang="pascal">
procedure _AddJob(oWriter: TxRestWriter; id: String);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT CONCAT(za_text, ":",sys_uid) AS Job FROM zeiterfart ' +
'WHERE za_psnr = ' + DB_SQLVal(id) + ' AND za_inaktiv <> "1" ' +
'ORDER BY za_order';
if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('Job'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddCustomer(oWriter: TxRestWriter);
var cSql : String;
A_Query : TxFQuery;
begin
cSql :=' SELECT * FROM' +
' (SELECT' +
' ps_nr,' +
' ps_such AS Kunde,' +
' perssta.sys_uid AS ps_sys_uid,' +
' "PE" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN perssta ON se_ref1 AND perssta.sys_uid = se_ref2' +
' WHERE se_nr = 0087' +
' AND ps_nr <> 100000' +
' UNION SELECT p_nr AS ps_nr,' +
' p_name1 AS ps_such,' +
' projekte.sys_uid AS ps_sys_uid,' +
' "PR" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN projekte ON se_ref1 = p_nr' +
' AND projekte.sys_uid = se_ref2 WHERE se_nr = 0087)' +
' A WHERE ps_nr IS NOT NULL' +
' ORDER BY Kunde ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('Kunde'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddID(oWriter: TxRestWriter; kunde: String);
var cSql : String;
A_Query : TxFQuery;
begin
cSql :=' SELECT * FROM' +
' (SELECT' +
' ps_nr,' +
' ps_such AS Kunde,' +
' perssta.sys_uid AS ps_sys_uid,' +
' "PE" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN perssta ON se_ref1 AND perssta.sys_uid = se_ref2' +
' WHERE se_nr = 0087' +
' AND ps_nr <> 100000' +
' UNION SELECT p_nr AS ps_nr,' +
' p_name1 AS ps_such,' +
' projekte.sys_uid AS ps_sys_uid,' +
' "PR" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN projekte ON se_ref1 = p_nr' +
' AND projekte.sys_uid = se_ref2 WHERE se_nr = 0087)' +
' A WHERE ps_nr IS NOT NULL' +
' AND Kunde = ' + DB_SQLVal(kunde) +
' ORDER BY Kunde ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('ps_nr'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddCHECK(oWriter: TxRestWriter);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT ze_starttime, zeiterfuser.sys_uid AS sysuid, zk_psnr, ' +
'za_text, ps_such, ze_startdate FROM ' +
'zeiterfuser LEFT JOIN zeiterfkomm ON ' +
'zk_messunguid = zeiterfuser.SYS_UID LEFT JOIN zeiterfart ' +
'ON zeiterfart.sys_uid = zeiterfuser.ze_uid AND ' +
'za_psnr = zeiterfkomm.zk_psnr LEFT JOIN perssta ON ' +
'ps_nr = zeiterfkomm.zk_psnr WHERE ze_status = 01 ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('ze_starttime'));
oWriter.Str('', A_Query.A2C('zk_psnr'));
oWriter.Str('', A_Query.A2C('za_text'));
oWriter.Str('', A_Query.A2C('ps_such'));
oWriter.Str('', A_Query.A2C('sysuid'));
oWriter.Str('', A_Query.A2C('ze_startdate'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _getPauseTime(oWriter: TxRestWriter; sysuid: String);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT * FROM zeiterfuser WHERE sys_uid = ' + DB_SQLVal(sysuid);

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('ze_pausezeit'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

//----------------Funktionen----------------------------------//

procedure POST(oReader: TxRestReader; oWriter: TxRestWriter);
var cChoice: String;
begin
cChoice := oReader.Param('choice');

// Jede dieser Antworten ist eine nackte Liste von Zeichenketten - genau
// so, wie das Javascript sie mit JSON.parse erwartet. RootArr sagt das
// und steht deshalb VOR dem ersten Eintrag.
if (cChoice = 'job') then begin
oWriter.RootArr();
_AddJob(oWriter, oReader.Param('id'));
end else if (cChoice = 'customer') then begin
oWriter.RootArr();
_AddCustomer(oWriter);
end else if (cChoice = 'id') then begin
oWriter.RootArr();
_AddID(oWriter, oReader.Param('selectedKunde'));
end else if (cChoice = 'check') then begin
oWriter.RootArr();
_AddCHECK(oWriter);
end else if (cChoice = 'pauseTime') then begin
oWriter.RootArr();
_GetPauseTime(oWriter, oReader.Param('sysuid'));
end else begin
// Eine unbekannte Auswahl war vorher eine leere Antwort - der Aufrufer
// sah einen Tippfehler nicht. Jetzt sagt es der Statuscode.
oWriter.Error(422, 'VALIDATION_FAILED', 'Unbekannte Auswahl: ' + cChoice);
end;
end;

procedure PUT(oReader: TxRestReader; oWriter: TxRestWriter);
var xZeit : TqSQL;
cUSER_SYSUID : String;
cKOMM_SYSUID : String;
lNew : Boolean;
cSql : String;
dDBNow : TDateTime;
cChoice : String;
begin
cChoice := oReader.Param('choice');
writeln('Choice: ' + cChoice);

if (cChoice = 'start') then begin
dDBNow := DB_Now(oDB);
lNew := True;
if (empty(cUSER_SYSUID)) then begin
cUSER_SYSUID := GetNewId(oDB);
end;

xZeit := qSqlInit(oDB, 'zeiterfuser');
xZeit.lNoSysUID := True;

writeln('SYSUID: ' + oReader.Param('jobID'));

xZeit.qSet('ze_user' , oReader.Param('user'));
xZeit.qSet('ze_starttime' , oReader.Param('uhrzeit'));
xZeit.qSet('ze_eigen' , '0101');
xZeit.qSet('ze_startdate' , oReader.Param('datum'));
xZeit.qSet('ze_endtime' , oReader.Param('endTime'));
xZeit.qSet('ze_enddate' , oReader.Param('endDate'));
xZeit.qSet('ze_zeit' , '0');
xZeit.qSet('ze_pausezeit' , '0');
xZeit.qSet('ze_status' , oReader.Param('status'));
xZeit.qSet('ze_berechnen' , 0);
xZeit.qSet('ze_officestar' , 0);
xZeit.qSet('ze_repa' , 0);
xZeit.qSet('ze_vorbereitung' , 0);
xZeit.qSet('ze_uid' , oReader.Param('jobID'));
xZeit.qSet('sys_uid' , cUSER_SYSUID);

// SaveData meldet einen Fehler ueber den RUECKGABEWERT, nicht ueber eine
// Exception. Ohne diese Pruefung antwortet der Endpunkt mit Erfolg,
// obwohl nichts geschrieben wurde.
if (not xZeit.SaveData(lNew)) then begin
qSQLFree(xZeit);
oWriter.Error(500, 'INTERNAL_ERROR', 'Zeiterfassung konnte nicht gespeichert werden');
exit;
end;
qSQLFree(xZeit);

//---------------------------------------------------------------------

xZeit := qSqlInit(oDB,'ZEITERFKOMM');
xZeit.lNoSysUID := True;

if (empty(cKOMM_SYSUID)) then begin
cKOMM_SYSUID := GetNewId(oDB);
end;

xZeit.qSet('zk_psnr' , oReader.Param('psnr'));
xZeit.qSet('zk_starttime' , oReader.Param('uhrzeit'));
xZeit.qSet('zk_startdate' , oReader.Param('datum'));
xZeit.qSet('zk_kommentar' , oReader.Param('comm'));
xZeit.qSet('zk_messunguid' , cUSER_SYSUID);
xZeit.qSet('sys_uid' , cKOMM_SYSUID);

if (not xZeit.SaveData(lNew)) then begin
qSQLFree(xZeit);
oWriter.Error(500, 'INTERNAL_ERROR', 'Kommentar konnte nicht gespeichert werden');
exit;
end;
qSQLFree(xZeit);

// Die UID steht jetzt in einem FELD und nicht mehr als nackter Text im
// Koerper. Der Writer kann nur JSON schreiben - und das ist gut so:
// eine Antwort, die manchmal 'ERROR: ...' und manchmal eine UID war,
// liess sich vom Aufrufer nicht unterscheiden. Das Javascript liest
// dafuer JSON.parse(...).uid, siehe timer.js.
oWriter.Str('uid', cUSER_SYSUID);

end else if (cChoice = 'stop') then begin

// Jeder Wert aus der Anfrage geht durch DB_SQLVal - auch die, die wie
// Zahlen aussehen. Der Kommentar ist Freitext aus dem Browser, und
// ohne Quoting beendet ein Apostroph darin das SQL-Statement.
cSql := 'UPDATE zeiterfuser, zeiterfkomm ' +
' SET zeiterfuser.ze_zeit = ' + DB_SQLVal(oReader.Param('elapsedTime')) +
', zeiterfuser.ze_endtime = ' + DB_SQLVal(oReader.Param('vergZeit')) +
', zeiterfuser.ze_enddate = ' + DB_SQLVal(oReader.Param('stopTimeValue')) +
', zeiterfuser.ze_pausezeit = ' + DB_SQLVal(oReader.Param('elapsedPauseTime')) +
', zeiterfuser.ze_status = ' + DB_SQLVal(oReader.Param('status')) +
', zeiterfkomm.zk_kommentar = ' + DB_SQLVal(oReader.Param('comment')) +
' WHERE zeiterfuser.sys_uid = ' + DB_SQLVal(oReader.Param('uid')) +
' AND zeiterfkomm.zk_messunguid = ' + DB_SQLVal(oReader.Param('uid'));

if (DB_SQLExec(oDB, cSql)) then begin
oWriter.Str('status', 'ok');
end else begin
// Ein Fehlschlag ist ein 500 und keine 200 mit dem Wort 'Fehler!'
// im Koerper - sonst haelt der Aufrufer ihn fuer einen Erfolg.
oWriter.Error(500, 'INTERNAL_ERROR', 'Die Daten konnten nicht gespeichert werden');
end;

end else if (cChoice = 'pause') then begin
writeln('Pausezeit: ' + oReader.Param('pauseTime'));
cSql := 'UPDATE zeiterfuser SET ze_pausezeit ' +
'= ze_pausezeit + ' + DB_SQLVal(oReader.Param('pauseTime')) +
' WHERE sys_uid = ' + DB_SQLVal(oReader.Param('sysuid'));

if (DB_SQLExec(oDB, cSql)) then begin
oWriter.Str('status', 'ok');
end else begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Die Pausenzeit konnte nicht gespeichert werden');
end;

end else begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Unbekannte Auswahl: ' + cChoice);
end;
end;
</syntaxhighlight>

= HTML-Datei index.php =
<syntaxhighlight lang="html">
<!DOCTYPE html>
<html lang="de-DE">
<head>
<title>Ihr IT-Partner in Stade - Ernst Bergau GmbH</title>
<link rel="stylesheet" type="text/css" href="timestyle.css">
</head>
<script>
<?php
include('timer.js');
?>
</script>
<body>




<textarea id="search" type="text" rows="1" cols="50" oninput="searchCustomers(this.value)"></textarea>

<div class="kundenliste">
<ul id="kundenListe"></ul>
</div>
<table class="timer">
<tbody id="timerList"></tbody>
</table>
<table class="tabelleUeberschriften">
<thead>
<tr>
<th class="kunde">Kunde</th>
<th class="konto">Konto</th>
<th class="laufzeit">Laufzeit</th>
<th class="status">Status</th>
</tr>
</thead>
</table>

<div class="lightbox" id="lightbox">
<label class="commLabel" id="commLabel" for="comment">Kommentar</label>
<textarea class="comment" id="comment" rows="4" cols="50"></textarea>

<div class="bezZeitkonto">Zeitkonto</div>
<select class="dropButtonsLightbox" id="tätigkeit2Dropdown"></select>

<div class="bezDatum">Startdatum</div>
<input type="date" class="date" id="date">

<textarea disabled class="uhrzeit" id="uhrzeit"></textarea>

<div class="bezPerson">Person</div>
<textarea disabled class="eingPerson" id="eingPerson"></textarea>
<textarea disabled class="eingPersonZusatz" id="eingPersonZusatz"></textarea>

<div class="Std">Std</div>
<input type="number" class="outStd" id="outStd">
<div class="Min">Min</div>
<input type="number" class="outMin" id="outMin">
<div class="Sek">Sek</div>
<input type="number" class="outSek" id="outSek">

<div class="Pausenzeiten">Davon Pausenzeiten</div>
<div class="Std2">Std</div>
<input type="number" class="outStd2" id="outStd2">
<div class="Min2">Min</div>
<input type="number" class="outMin2" id="outMin2">
<div class="Sek2">Sek</div>
<input type="number" class="outSek2" id="outSek2">

<button class="saveButton" id="saveButton">Speichern</button>
<button class="closeButton" id="closeButton" onclick="closeLightboxOnSchliessen()">Schließen</button>
</div>

<div id="zweiteListe">
<ul id="taetigkeitListe"></ul>
</div>
</body>
</html>

</syntaxhighlight>

= Javascript-Datei timer.js =
<syntaxhighlight lang="javascript">
var api_key = 'Y00C75PODJ';
var url = 'http://127.0.0.1:8099/Zeiterfa/zeiterfa/v1';
var zaehler = -1;
var timerInterval;
var pauseTimerInterval;
var startTimeValue;
var selectedID = 0;
var elapsedTime;
var uid;
var idStop;
var time;
var selID = [];
var job = [];
var sys_uid = [];
var timers = [];
var pauseTimers = [];
var pauseTime = [];
var startdate = [];
var uhrzeit = [];
var datum = [];
var statusTimer = [];
var selectedJob = [];
var selectedKunde = [];
var tempSelectedKunde = [];
var parameter = [];

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------------Seitenaufruf---------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Bei Seitenaufruf werden die Funktionen----//
//----getCustomer und checkTimer aufgerufen und----//
//----die Kundenliste gefüllt und geprüft,----//
//----ob laufende timer vorhanden sind----//

window.onload = function() {

getCustomer();
checkTimer();
}

//-----------------------------------------------------------------------------------------------------------------------//
//-------------------------------------------------Daten auslesen--------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Eine Liste der Kunden wird ausgelesenund gespeichert----//

function getCustomer() {

var method = 'POST';
var choice = 'customer';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
populateListeKunde(responseData);
}
};
request.send(params);
}

//----Bei Rechtsklick auf Kunden wird----//
//----seine ID ausgelesen und gespeichert----//

function getCustomerID(selectedKunde, callback) {

var method = 'POST';
var choice = 'id';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&selectedKunde=" + encodeURIComponent(selectedKunde);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
selectedID = JSON.parse(request.responseText);
callback(selectedID);
}
};
request.send(params);
}

//----Anhand der Kunden-ID wird eine Liste von Tätigkeiten----//
//----für jeden Kunden ausgelesen und gespeichert----//

function getJob(id, callback) {

var method = 'POST';
var choice = 'job';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&id=" + encodeURIComponent(id);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
var Data = responseData.toString();
var teile = Data.split(",");
var jobid = [];

for (i=0; i<teile.length; i++) {
job[i] = teile[i].split(":")[0];
jobid[i] = teile[i].split(":")[1];
}
callback(job, jobid);
}
};
request.send(params);
}

//----Tätigkeitsliste wird nochmal zur Weiterverarbeitung gelesen----//

function getJobs(id) {

var method = 'POST';
var choice = 'job';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&id=" + encodeURIComponent(id);

var request = new XMLHttpRequest();

request.open("POST", "getData.php", false);
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
var data = responseData.toString();
var teile = data.split(",");
var jobid = [];

for (var i = 0; i < teile.length; i++) {
job[i] = teile[i].split(":")[0];
jobid[i] = teile[i].split(":")[1];
}
}
};
request.send(params);
}

//----Gespeicherte Pausezeit wird ausgelesen----//

function getPauseTime(sysuid, id) {

var method = 'POST';
var choice = 'pauseTime';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&sysuid=" + encodeURIComponent(sysuid);

var request = new XMLHttpRequest();

request.open("POST", "getData.php", false);
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
pauseTime[id].value = JSON.parse(request.responseText);

}
};
request.send(params);
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Listen--------------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Eine Liste wird mit Kundendaten gefüllt und angezeigt----//

function populateListeKunde(data) {

data.forEach(function(item) {
var listItem = document.createElement("li");
listItem.textContent = item;

listItem.addEventListener("contextmenu", function(event) {
event.preventDefault();

var selectedKunde = item;
getCustomerID(selectedKunde, function(selectedID) {
getJob(selectedID, function(job, jobid) {
showSecondList(job, jobid, item);
});
});
});

kundenListe.appendChild(listItem);
});
}

//----Eine zweite Liste wird mit Jobs gefüllt,----//
//----angezeigt und bei Klick auf einen Eintrag---//
//-------die Funktion startTimer aufgerufen-------//

function showSecondList(job, jobid, kundeItem) {

var zweiteListe = document.getElementById("zweiteListe");
zweiteListe.innerHTML = "";

job.forEach(function(item) {
var listItem = document.createElement("li");
listItem.textContent = item;

(function(capturedItem) {
listItem.addEventListener("click", function() {
startTimer(job, jobid, capturedItem, kundeItem);
});
}) (item);
zweiteListe.appendChild(listItem);
});

zweiteListe.style.display = "block";
document.addEventListener('keydown', closeSecondList);
document.addEventListener('click', closeSecondList);
}

//----Nach Klick auf Eintrag wird die Liste geschlossen----//
function closeSecondList() {

var zweiteListe = document.getElementById("zweiteListe");
zweiteListe.style.display = "none";
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Daten speichern-----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Startzeit, -datum, ID und Job werden gespeichert----//

function saveStartTime(user, uhrzeit, datum, endTime, endDate, status, psnr, Job, jobID) {

var method = 'PUT';
var choice = 'start';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&user=" + encodeURIComponent(user) +
"&uhrzeit=" + encodeURIComponent(uhrzeit) +
"&datum=" + encodeURIComponent(datum) +
"&endTime=" + encodeURIComponent(endTime) +
"&endDate=" + encodeURIComponent(endDate) +
"&status=" + encodeURIComponent(status)+
"&psnr=" + encodeURIComponent(psnr)+
"&Job=" + encodeURIComponent(Job)+
"&jobID=" + encodeURIComponent(jobID);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
// Die Antwort ist JSON: {"uid":"..."} - vorher stand die UID als
// nackter Text im Koerper.
sys_uid[zaehler].value = JSON.parse(request.responseText).uid;
}
};
request.send(params);
}

//----Pausezeit wird gespeichert----//

function savePauseTime(pauseTime, id) {

var method = 'PUT';
var choice = 'pause';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&pauseTime=" + encodeURIComponent(pauseTime) +
"&sysuid=" + encodeURIComponent(sys_uid[id].value);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {

if (this.readyState === 4 && this.status === 200) {
// alert(request.responseText);
}
};
request.send(params);
}

//----Stopzeit und -datum wird gespeichert----//

function saveStopTime(stopTimeValue, elapsedTime, elapsedPauseTime, status, uid, vergZeit, comment) {

var method = 'PUT';
var choice = 'stop';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&stopTimeValue=" + encodeURIComponent(stopTimeValue) +
"&elapsedTime=" + encodeURIComponent(elapsedTime) +
"&elapsedPauseTime=" + encodeURIComponent(elapsedPauseTime) +
"&status=" + encodeURIComponent(status) +
"&uid=" + encodeURIComponent(uid) +
"&vergZeit=" + encodeURIComponent(vergZeit)+
"&comment=" + encodeURIComponent(comment);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200 && timers.length === 0) {
location.reload();
}
};
request.send(params);
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Like-Suche----------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Durchsucht die Liste der Kunden auf alle einegegebenen Zeichen----//

function searchCustomers(text) {

text = text.toLowerCase();
var kundenListe = document.getElementById("kundenListe");
var listItems = kundenListe.getElementsByTagName("li");

for (i=0; i<listItems.length; i++) {
var item = listItems[i].textContent.toLowerCase();
if (item.includes(text)) {
listItems[i].style.display = "block";
}
else {
listItems[i].style.display = "none";
}
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------Vorhandenen Timer checken----------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Überprüft, ob es Einträge in Datenbank ohne----//
//----Endzeit gibt und startet entsprechend Timer----//

function checkTimer() {

var method = 'POST';
var choice = 'check';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200 && timers.length === 0) {
var responseData = JSON.parse(request.responseText);

if (responseData.length !== 0) {
startTimeValue = new Date();
var minutes = startTimeValue.getMinutes();
var seconds = startTimeValue.getSeconds();
var month = startTimeValue.getMonth() + 1;

responseData = responseData.toString();
var teile = responseData.split(",");

for (var i=0; i<teile.length; i+=6) {
uhrzeit.push({value: startTimeValue.getHours() + ":" + (minutes < 10 ? "0" + minutes : minutes) + ":" + (seconds < 10 ? "0" + seconds : seconds)});
datum.push({value: startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + startTimeValue.getDate()});

zaehler++;

statusTimer.push({value: 'Running'});
pauseTimers.push({value: 0});
pauseTime.push({value: 0});
timers.push({value: teile[i]});
}

var j=0;
for (var i=1; i<teile.length; i+=6) {
selID.push({value: teile[i]});
getJobs(selID[j].value);
j++;
}

fillArray(2, selectedJob, teile);
fillArray(3, selectedKunde, teile);
fillArray(4, sys_uid, teile);
fillArray(5, startdate, teile);

for (var i=0; i<timers.length; i++) {
var startZeitTeil = timers[i].value.split(":");
var startDatumTeil = startdate[i].value.split(".");

var diffMilli = new Date() - getStartdatum(startDatumTeil, startZeitTeil);
timers[i].value = Math.floor(diffMilli / 1000);
}

selecteID = 0;
startInterval(job);
}
}
};
request.send(params);
}

//----Arrays werden an diese Funktion übergeben und gefüllt----//

function fillArray(LZ, array, teile) {

var arrLZ = 0;
for (var i=LZ; i<teile.length; i+=6) {
array.push({value: teile[i]});
arrLZ++;
}
}

//----Startdatum wird errechnet----//
function getStartdatum(startDatumTeil, startZeitTeil) {

var startdatum = new Date(
parseInt(startDatumTeil[2]),
parseInt(startDatumTeil[1]) -1,
parseInt(startDatumTeil[0]),
parseInt(startZeitTeil[0]),
parseInt(startZeitTeil[1]),
parseInt(startZeitTeil[2])
);
return startdatum;
}

//-----------------------------------------------------------------------------------------------------------------------//
//-------------------------------------------------Interval--------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Interval für Timer wird gestartet----//

function startInterval(job, item, kundeItem, index) {

timerInterval = setInterval(function() {

for (i=0; i<timers.length; i++) {

timers[i].value += 1;
}
updateUI(job, item, kundeItem, index);
}, 1000);
}

//----Interval für Pausentimer wird gestartet----//

function pauseInterval(job, item, kundeItem, id) {

pauseTimerInterval = setInterval(function() {

for (i=0; i<pauseTimers.length; i++) {

pauseTimers[i].value += 1;
}
updateUI(job, item, kundeItem);
}, 1000);
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer starten----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----startTimer bereitet die nötigen Arrays vor,----//
//----speichert Startzeit und -datum,----//
//----beschreibt Arrays und Variablen entsprechend----//
//----und ruft die Funktion saveStartTime auf----//

function startTimer(jobs, jobid, selJob, kundeItem) {

var user = 999;
var endTime = "00:00:00";
var endDate = "0000-00-00";
var status = '01';
zaehler++;

startTimeValue = new Date();

var minutes = startTimeValue.getMinutes();
var seconds = startTimeValue.getSeconds();
uhrzeit.push({value: startTimeValue.getHours() + ":" + (minutes < 10 ? "0" + minutes : minutes) + ":" + (seconds < 10 ? "0" + seconds : seconds)});

var month = startTimeValue.getMonth() + 1;
datum.push({value: startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + startTimeValue.getDate()});

statusTimer.push({value: 'Running'});
pauseTimers.push({value: 0});
pauseTime.push({value: 0});
timers.push({value: 0});
selectedKunde.push({value: kundeItem});
selectedJob.push({value: selJob});
sys_uid.push({value: 0});

var index = jobs.indexOf(selJob);

saveStartTime(user, uhrzeit[zaehler].value, datum[zaehler].value, endTime, endDate, status, selectedID, selJob, jobid[index]);

clearInterval(timerInterval);
startInterval(jobs, selJob, kundeItem, index);

zweiteListe.style.display = "none";
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer stoppen----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Stopt den Timer, ändert den Status und ruft openLightbox auf----//

function stopTimer(job, item, kundeItem, index, id) {

idStop = id;
statusTimer[id].value = 'Stopped';
openLightbox(job, item, kundeItem, index, id);
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer pausieren--------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Pausiert den Timer und ändert den Status----//

function pauseTimer(job, item, kundeItem, id) {

pauseTimers[id].value = 0;
clearInterval(pauseTimerInterval);
pauseInterval(job, item, kundeItem, id);
}

//-----------------------------------------------------------------------------------------------------------------------//
//----------------------------------------------Button Pause-Start-------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Ruft die Funktion pauseTimer oder----//
//----savePauseTimer auf----//

function toggleButton(job, item, kundeItem, id) {

var button = document.getElementById(id);

if (button.innerHTML === "Pause") {

statusTimer[id].value = 'Paused';
pauseTimer(job, item, kundeItem, id);
}
else {

statusTimer[id].value = "Running";
savePauseTime(pauseTimers[id].value, id);
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Ausgabe des Timers-----------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Zeigt eine Liste mit einem oder mehreren----//
//----Timern und Buttons, verteilt dynamisch ID's----//
//----und ruft entsprechend der gedrückten----//
//----Buttons Funktionen auf----//

function updateUI(job, item, kundeItem, index) {
var timerList = document.getElementById("timerList");
timerList.innerHTML = '';

for (i=0; i<timers.length; i++) {
var neueReihe = document.createElement('tr')

//----Name des Kunden wird ausgegeben----//

var kundeEintrag = document.createElement('td');
kundeEintrag.style.position = "fixed";
kundeEintrag.style.top = (12 + i * 14) + "%";
kundeEintrag.style.width = "30%";
kundeEintrag.style.left = "0%";
kundeEintrag.style.textAlign = "center";
kundeEintrag.classList.add('kunde_k');
kundeEintrag.textContent = selectedKunde[i].value;
timerList.appendChild(kundeEintrag);

//----Gewählter Job wird ausgegeben----//

var kontoEintrag = document.createElement('td');
kontoEintrag.style.position = "fixed";
kontoEintrag.style.top = (12 + i * 14) + "%";
kontoEintrag.style.width = "30%";
kontoEintrag.style.left = "30%";
kontoEintrag.style.textAlign = "center";
kontoEintrag.classList.add('konto_k');
kontoEintrag.textContent = selectedJob[i].value;
timerList.appendChild(kontoEintrag);

//----Gestartete Timer werden in Liste----//
//----ausgegeben, pausierte Timer werden----//
//----Liste ausgegeben, sobald Timer gestoppt----//
//----wird Ausgabe in Lightbox----//

if (statusTimer[i].value === "Running") {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(timers[i].value);
timerList.appendChild(laufzeitElement);
}
else if (statusTimer[i].value === 'Paused') {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(pauseTimers[i].value);
timerList.appendChild(laufzeitElement);
}
else if (statusTimer[i].value === 'Stopped') {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(pauseTimers[i].value);
timerList.appendChild(laufzeitElement);

var zeit = formatElapsedTime(timers[i].value);
zeit = zeit.toString();
var teile = zeit.split(":");

var h = teile[0];
var m = teile[1];
var s = teile[2];

var outStdField = document.getElementById("outStd");
var outMinField = document.getElementById("outMin");
var outSekField = document.getElementById("outSek");

if (document.activeElement !== outStdField && document.activeElement !== outMinField && document.activeElement !== outSekField) {
document.getElementById("outStd").value = h;
document.getElementById("outMin").value = m;
document.getElementById("outSek").value = s;
}

var hEnd = document.getElementById("outStd").value;
var mEnd = document.getElementById("outMin").value;
var sEnd = document.getElementById("outSek").value;
time = hEnd + ":" + mEnd + ":" + sEnd;
}

//----Status (Running, Paused, Stopped) wird ausgegeben----//

var statusTimerElement = document.createElement('td');
statusTimerElement.style.position = "fixed";
statusTimerElement.style.top = (12 + i * 14) + "%";
statusTimerElement.style.width = "15%";
statusTimerElement.style.left = "75%";
statusTimerElement.style.textAlign = "center";
statusTimerElement.classList.add('status_s');
statusTimerElement.textContent = statusTimer[i].value;
timerList.appendChild(statusTimerElement);

//----Pause Button mit dynamisch vergebener ID wird ausgegeben----//

if (statusTimer[i].value === "Running") {
var pauseButton = document.createElement('button')
pauseButton.id = i;
pauseButton.classList.add('pauseButton');
pauseButton.style.position = "fixed";
pauseButton.style.top = (12 + i * 14) + "%";
pauseButton.style.left = "90%";
pauseButton.style.height = "9.4%";
pauseButton.style.minWidth = "3%";
pauseButton.style.fontSize = "80%";
pauseButton.textContent = "Pause"
pauseButton.addEventListener('click', function() {toggleButton(job, item, kundeItem, this.id)});
timerList.appendChild(pauseButton);
}
else if (statusTimer[i].value === "Paused") {
var pauseButton = document.createElement('button')
pauseButton.id = i;
pauseButton.classList.add('pauseButton');
pauseButton.style.position = "fixed";
pauseButton.style.top = (12 + i * 14) + "%";
pauseButton.style.left = "90%";
pauseButton.style.height = "9.4%";
pauseButton.style.minWidth = "3%";
pauseButton.style.fontSize = "80%";
pauseButton.textContent = "Start"
pauseButton.addEventListener('click', function() {toggleButton(job, item, kundeItem, this.id)});
timerList.appendChild(pauseButton);
}

//----Stop Button mit dynamisch vergebener ID wird ausgegeben----//

var stopButton = document.createElement('button')
stopButton.id = i;
stopButton.classList.add('stopButton');
stopButton.style.position = "fixed";
stopButton.style.top = (12 + i * 14) + "%";
stopButton.style.left = "94%";
stopButton.style.height = "9.4%";
stopButton.style.width = "3%";
stopButton.style.fontSize = "80%";
stopButton.textContent = "Stop"
stopButton.addEventListener('click', function() {stopTimer(job, item, kundeItem, index, this.id)});
timerList.appendChild(stopButton);

//----Für jeden aufgerufenen Timer wird----//
//----eine neue Reihe ausgegeben----//

timerList.appendChild(neueReihe);
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//-----------------------------------------------Sekunden in Uhrzeit umrechnen-------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Rechnet übergebene Sekunden in Stunden,----//
//----Minuten und Sekunden und gibt diese----//
//----an aufrufende Funktion zurück----//

function formatElapsedTime(seconds) {

var minutes = Math.floor(seconds / 60);
seconds %= 60;
var hours = Math.floor(minutes / 60);
minutes %= 60;
function addLeadingZero(n) {
return (n < 10 ? '0' : '') + n;
}

return addLeadingZero(hours) + ":" + addLeadingZero(minutes) + ":" + addLeadingZero(seconds);
}

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------Uhrzeit in Sekunden umrechnen----------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Rechnet übergebene Stunden, Minuten----//
//----und Sekunden in Sekunden um und----//
//----gibt diese an aufrufende Funktion zurück----//

function timeInSeconds(zeit) {

var teile = zeit.split(':');
var Stunden = parseInt(teile[0], 10);
var Minuten = parseInt(teile[1], 10);
var Sekunden = parseInt(teile[2], 10);
return Stunden * 3600 + Minuten * 60 + Sekunden;
}

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------------Lightbox-------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Öffnet eine Lightbox und zeigt Kunde----//
//----Job, vergangene Zeit und evtl Pausenzeit an----//
//----und gibt Möglichkeit alle Zeiten anzupassen----//

function openLightbox(job, item, kundeItem, index, id) {

document.getElementById('lightbox').style.display = 'block';

var dateField = document.getElementById("date");
dateField.value = datum[id].value;
document.getElementById("uhrzeit").innerHTML = uhrzeit[id].value;

var commentTextarea = document.getElementById("comment");
commentTextarea.value = selectedJob[id].value;

document.getElementById("eingPersonZusatz").innerHTML = selectedKunde[id].value;

if (selectedID.length !== undefined) {
document.getElementById("eingPerson").innerHTML = selectedID;
}
else {
document.getElementById("eingPerson").innerHTML = selID[id].value;
}

//----Ausgabe der vergangenen Zeit in Lightbox----//

document.getElementById("outStd").value = 00;
document.getElementById("outMin").value = 00;
document.getElementById("outSek").value = 00;

//----Ausgabe der Pausenzeiten in Lightbox----//

document.getElementById("outStd2").value = 00;
document.getElementById("outMin2").value = 00;
document.getElementById("outSek2").value = 00;
getPauseTime(sys_uid[id].value, id);

var secondsPause = pauseTime[id].value;
secondsPause %= 60;

var minutesPause = Math.floor(pauseTime[id].value / 60);
minutesPause %= 60;

var hoursPause = Math.floor(minutesPause / 60);
hoursPause %= 60;

document.getElementById("outStd2").value = hoursPause;
document.getElementById("outMin2").value = minutesPause;

if (secondsPause > 0) {
document.getElementById("outSek2").value = secondsPause;
}
else {
document.getElementById("outSek2").value = 0;
}

var dropdown2 = document.getElementById("tätigkeit2Dropdown");

job.forEach(function(item, index) {
var option = document.createElement("option");
option.textContent = item;
dropdown2.add(option)

if (item === selectedJob[id].value) {
option.selected = true;
}
});

document.addEventListener('keydown', closeLightboxOnEscape);
document.addEventListener('keydown', closeLightboxOnF2);
}

//----Lightbox schließen----//

function closeLightbox() {

document.getElementById('lightbox').style.display = 'none';
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn der Schließen-Button gedrückt wird----//

function closeLightboxOnSchliessen() {

statusTimer[idStop].value = 'Running';
closeLightbox();
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn Escape gedrückt wird----//

function closeLightboxOnEscape() {

if (event.key === 'Escape') {
statusTimer[idStop].value = 'Running';
closeLightbox();
}
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn F2 gedrückt wird----//

function closeLightboxOnF2(event) {

if (event.key === 'F2') {
saveBox();
closeLightbox();
}
}

//----Alle Daten in Lightbox werden gespeichert----//

function saveBox() {

var vergZeit = '"' + time + '"';

var teile = time.split(":");
var stunden = parseInt(teile[0]);
var minuten = parseInt(teile[1]);
var sekunden = parseInt(teile[2]);
time = stunden * 3600 + minuten * 60 + sekunden;

elapsedTime = time;

var comment = '"' + document.getElementById("comment").value + '"';

var hPEnd = document.getElementById("outStd2").value;
var mPEnd = document.getElementById("outMin2").value;
var sPEnd = document.getElementById("outSek2").value;
var pTime = hPEnd + ":" + mPEnd + ":" + sPEnd;
pTime = timeInSeconds(pTime);

var uid = sys_uid[idStop].value;
var month = startTimeValue.getMonth();
var day = startTimeValue.getDate();
month += 1;
var stopTimeValue = '"' + startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + (day < 10 ? "0" + day : day) + '"';

var status = 21;

timers.splice(idStop, 1);
pauseTimers.splice(idStop, 1);
pauseTime.splice(idStop, 1);
selectedKunde.splice(idStop, 1);
selectedJob.splice(idStop, 1);
statusTimer[idStop].value = 'Running';
sys_uid.splice(idStop, 1);

if (zaehler > 0) {
zaehler -= 1;
}

closeLightbox();

if (timers.length === 0) {
clearInterval(timerInterval);
}

saveStopTime(stopTimeValue, elapsedTime, pTime, status, uid, vergZeit, comment);
}

//----Funktion saveBox wird aufgerufen,----//
//----wenn der Save-Button gedrückt wird----//

document.addEventListener('DOMContentLoaded', function() {
const saveButton = document.getElementById('saveButton');
saveButton.addEventListener('click', function() {
saveBox();
})
});
</syntaxhighlight>

= PHP-Script saveTime.php =
<syntaxhighlight lang="php">
<?php
$user = 0;
$uhrzeit = 0;
$datum = 0;
$endTime = 0;
$endDate = 0;
$status = 0;
$psnr = 0;
$comm = 0;
$jobID = 0;
$pauseTime = 0;
$sysuid = 0;
$stopTimeValue = 0;
$elapsedTime = 0;
$elapsedPauseTime = 0;
$status = 0;
$uid = 0;
$vergZeit = 0;

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$api_key = $_POST['api_key'];
$url = $_POST['url'];
$method = $_POST['method'];
$choice = $_POST['choice'];

if (isset($_POST['user'])) {
$user = $_POST['user'];
}
if (isset($_POST['uhrzeit'])) {
$uhrzeit = $_POST['uhrzeit'];
}
if (isset($_POST['datum'])) {
$datum = $_POST['datum'];
}
if (isset($_POST['endTime'])) {
$endTime = $_POST['endTime'];
}
if (isset($_POST['endDate'])) {
$endDate = $_POST['endDate'];
}
if (isset($_POST['status'])) {
$status = $_POST['status'];
}
if (isset($_POST['psnr'])) {
$psnr = $_POST['psnr'];
}
if (isset($_POST['Job'])) {
$comm = $_POST['Job'];
}
if (isset($_POST['jobID'])) {
$jobID = $_POST['jobID'];
}
if (isset($_POST['pauseTime'])) {
$pauseTime = $_POST['pauseTime'];
}
if (isset($_POST['sysuid'])) {
$sysuid = $_POST['sysuid'];
}
if (isset($_POST['stopTimeValue'])) {
$stopTimeValue = $_POST['stopTimeValue'];
}
if (isset($_POST['elapsedTime'])) {
$elapsedTime = $_POST['elapsedTime'];
}
if (isset($_POST['elapsedPauseTime'])) {
$elapsedPauseTime = $_POST['elapsedPauseTime'];
}
if (isset($_POST['status'])) {
$status = $_POST['status'];
}
if (isset($_POST['uid'])) {
$uid = $_POST['uid'];
}
if (isset($_POST['vergZeit'])) {
$vergZeit = $_POST['vergZeit'];
}

$params = array( 'user' => $user,
'uhrzeit' => $uhrzeit,
'datum' => $datum,
'endTime' => $endTime,
'endDate' => $endDate,
'status' => $status,
'psnr' => $psnr,
'comm' => $comm,
'jobID' => $jobID,
'pauseTime' => $pauseTime,
'sysuid' => $sysuid,
'stopTimeValue' => $stopTimeValue,
'elapsedTime' => $elapsedTime,
'elapsedPauseTime' => $elapsedPauseTime,
'status' => $status,
'uid' => $uid,
'vergZeit' => $vergZeit,
'choice' => $choice);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('apikey: '.$api_key));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($params));
$response = curl_exec($curl);

if ($response === false) {
if($error) {
echo "curl_Fehler: ".$error;
}
}
else {
echo $response;
}
}
?>
</syntaxhighlight>

= PHP-Script getData.php =
<syntaxhighlight lang="php">
<?php
$sysuid = 0;
$id = 0;
$selectedKunde = 0;

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$api_key = $_POST['api_key'];
$url = $_POST['url'];
$method = $_POST['method'];
$choice = $_POST['choice'];

if (isset($_POST['id'])) {
$id = $_POST['id'];
}
if (isset($_POST['sysuid'])) {
$sysuid = $_POST['sysuid'];
}
if (isset($_POST['selectedKunde'])) {
$selectedKunde = $_POST['selectedKunde'];
}

$params = array( 'sysuid' => $sysuid,
'id' => $id,
'selectedKunde' => $selectedKunde,
'choice' => $choice);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('apikey: '.$api_key));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($params));
$response = curl_exec($curl);

if ($response === false) {
if($error) {
echo "curl_Fehler: ".$error;
}
}
else {
echo $response;
}
}
?>
</syntaxhighlight>

= CSS-Datei timestyle.css =
<syntaxhighlight lang="css">
/*-------------------------------------------------------------------------------------------------*/
/*-----------------------------------------Allgemein-----------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

body
{
font-family: 'Arial', sans-serif;
display: flex;
justify-content: right;
align-items: flex-start;
height: 100%;
background-image: url('web_background_3.png');
background-repeat: no-repeat;
background-size: cover;
background-attachment: fixed;
}
ul
{
list-style-type: none;
}
li
{
padding: 0.5em;
cursor: pointer;
display: flex;
justify-content: space-between;
align-items: center;
font-size: 0.85em;
}

/*-------------------------------------------------------------------------------------------------*/
/*-------------------------------------------Suche-------------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

#search
{
position: fixed;
top: 8%;
left: 42%;
width: 15%;
height: 2.8%;
resize: none;
border: 0.04em solid #e4e4e4;
border-radius: 0.1em;
background-color: white;
font-size: 2em;
overflow: hidden;
}

/*-------------------------------------------------------------------------------------------------*/
/*-----------------------------------------Timerausgabe--------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

.kundenliste
{
width: 70%;
height: 30%;
position: fixed;
top: 43.5%;
left: 50%;
transform: translate(-50%, -50%);
border-top-left-radius: 0.2em;
border-top-right-radius: 0.2em;
overflow: auto;
background-color: white;
font-size: 0.85vw;
}
.tabelleUeberschriften
{
width: 70%;
min-height: 3%;
position: fixed;
top: 60%;
left: 50%;
transform: translate(-50%, -50%);
/* border-top: 0.14em solid #ccc;
border-bottom: 0.14em solid #ccc; */
background-color: white;
box-shadow: 0 0px 3px rgba(0, 0, 0, 0.5);
font-size: 0.9vw;
}
#timerList
{
width: 70%;
height: 25%;
position: fixed;
top: 73.5%;
left: 50%;
transform: translate(-50%, -50%);
overflow: auto;
border-bottom-left-radius: 0.2em;
border-bottom-right-radius: 0.2em;
/* border: 0.14em solid red; */
background-color: white;
font-size: 0.85vw;
}
.kunde
{
width: 30%;
position: fixed;
left: 0%;
}
.konto
{
width: 30%;
position: fixed;
left: 30%;
}
.laufzeit
{
width: 15%;
position: fixed;
left: 60%;
}
.status
{
width: 15%;
position: fixed;
left: 75%;
}
.buttons
{
width: 10%;
position: fixed;
left: 90%;
}

/*-------------------------------------------------------------------------------------------------*/
/*-------------------------------------------Lightbox----------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

.lightbox
{
display: none;
width: 52%;
height: 62%;
position: fixed;
top: 61.5%;
left: 67%;
border-radius: 0.15em;
background-color: white;
transform: translate(-50%, -50%);
flex-direction: column;
align-items: center;
box-shadow: 0 10px 2000px rgba(0, 0, 0, 0.5);
}

/*-----------------------------------------Lightbox-Inhalt-----------------------------------------*/

.commLabel
{
position: fixed;
top: 5%;
left: 5%;
font-weight: bold;
font-size: 0.8vw;
}
.comment
{
width: 90%;
height: 38%;
position: fixed;
top: 10%;
left: 5%;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.9vw;
}

.bezZeitkonto
{
position: fixed;
top: 55%;
left: 5%;
font-size: 0.8vw;
}
.dropButtonsLightbox
{
width: 37%;
height: 4.4%;
position: fixed;
top: 54%;
left: 15%;
font-size: 0.7vw;
}
.bezDatum
{
position: fixed;
top: 55%;
left: 58%;
font-size: 0.7vw;
}
.date
{
position: fixed;
top: 54%;
left: 68%;
width: 15%;
height: 4%;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
}
.uhrzeit
{
position: fixed;
top: 54%;
left: 85.5%;
width: 10%;
height: 3.9%;
padding: 0.1em;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
resize: none;
}

.bezPerson
{
position: fixed;
top: 68%;
left: 5%;
font-size: 0.8vw;
}
.eingPerson
{
position: fixed;
top: 68%;
left: 15%;
width: 10%;
height: 4.4%;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
}
.eingPersonZusatz
{
position: fixed;
top: 68%;
left: 26%;
width: 25.7%;
height: 4.4%;
overflow: auto;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
}
.Std
{
position: fixed;
top: 63%;
left: 66%;
font-size: 0.7vw;
}
.Min
{
position: fixed;
top: 63%;
left: 78%;
font-size: 0.7vw;
}
.Sek
{
position: fixed;
top: 63%;
left: 91%;
font-size: 0.7vw;
}
.outStd
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 64%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outMin
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 76.5%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outSek
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 89%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}

.Pausenzeiten
{
position: absolute;
top: 79%;
left: 71%;
font-weight: bold;
font-size: 0.8vw;
}
.Std2
{
position: fixed;
top: 84%;
left: 66%;
font-size: 0.7vw;
}
.Min2
{
position: fixed;
top: 84%;
left: 78%;
font-size: 0.7vw;
}
.Sek2
{
position: fixed;
top: 84%;
left: 91%;
font-size: 0.7vw;
}
.outStd2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 64%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outMin2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 76.5%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outSek2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 89%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.saveButton
{
min-width: 8%;
height: 4.4%;
position: fixed;
top: 89%;
left: 5%;
font-size: 0.7vw;
}
.closeButton
{
min-width: 8%;
height: 4.4%;
position: fixed;
top: 89%;
left: 14%;
font-size: 0.7vw;
}

/*-------------------------------------------------------------------------------------------------*/
/*--------------------------------Tätigkeitenliste (zweite Liste)----------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

#zweiteListe
{
display: none;
width: 25%;
max-height: 50%;
position: fixed;
top: 47%;
left: 44%;
padding: 1%;
overflow: auto;
border-radius: 0.2em;
transform: translate(-50%, -50%);
background-color: #FAFAFA;
box-shadow: 0 10px 2000px rgba(0, 0, 0, 0.5);
font-size: 0.85vw;
}

</syntaxhighlight>

OBS/Kostenpflichtige Module/RESTServer/Beispiel4

2026-09-09T12:31:45Z

Rademacker:

{{Kostenpflichtige Module}}
= Beispiel 4 – Pfad-Parameter (REST-Routing über Templates) =

Dieses Beispiel zeigt das '''Pfad-Template-Routing''' mit Platzhaltern. Eine
Auftrags-Ressource wird über drei Endpunkte abgebildet:

{| class="wikitable"
! Methode + Pfad !! Zweck
|-
| <code>GET /orders</code> || Liste aller offenen Aufträge
|-
| <code>GET /orders/{uid}</code> || Einzelner Auftrag per UID
|-
| <code>PUT /orders/{uid}/modules/{code}</code> || Status eines Auftrags-Moduls ändern
|}

Die Platzhalter <code>{uid}</code> und <code>{code}</code> stehen im Skript als
<code>oReader.Path('uid')</code> bzw. <code>oReader.Path('code')</code> zur
Verfügung.

== Einrichtung in OBS ==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' auf <code>0.0.0.0:443</code>.
* '''Zugang:''' ''Orders-Client'' mit API-Key, Zugriff auf die drei Endpunkte.
* '''Endpunkte''' (je ein Eintrag in <code>RESTSRV_ENDPOINTS</code>, alle Profil ''Public-API''):

{| class="wikitable"
! Endpunkt !! Pfad-Template !! Skript-Methode
|-
| <code>orders</code> || <code>/orders</code> || <code>Get</code> (Liste)
|-
| <code>orders</code> || <code>/orders/{uid}</code> || <code>Get</code> (Einzel)
|-
| <code>orders</code> || <code>/orders/{uid}/modules/{code}</code> || <code>Put</code>
|}

== Endpunkt-Skript 1: <code>GET /orders</code> (Liste) ==

<syntaxhighlight lang="pascal">
// Hilfsfunktion: die FELDER eines Auftrags. Der Helfer bekommt den Writer und
// schreibt in das Objekt, das der Aufrufer schon geoeffnet hat - so laesst sich
// derselbe Auftrag einmal als Listeneintrag und einmal als ganze Antwort
// ausgeben, ohne den Code zu verdoppeln.
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TqSQL;
const cOffset: string);
begin
oWriter.Str ('uid' , qOrder.A2UID());
oWriter.Str ('nr' , qOrder.A2C('au_nr'));
oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
oWriter.Str ('status', qOrder.A2C('au_status'));
// ISO-8601 mit Offset - siehe den Hinweis unter der Liste.
oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
qData : TqSQL;
cOffset: string;
begin
cOffset := oReader.Offset();
// Die Antwort ist eine nackte Liste - RootArr vor dem ersten Eintrag.
// Findet die Abfrage nichts, ist es eine leere Liste und kein leeres
// Objekt: deshalb steht der Aufruf VOR der Abfrage.
oWriter.RootArr();

cSql := 'SELECT * FROM auftraege' +
' WHERE au_status <> ' + DB_SQLVal('9') +
' ORDER BY au_nr';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oWriter.ObjBegin('');
_OrderFelder(oWriter, qData, cOffset);
oWriter.ObjEnd;
qData.Next();
end;
end;
DB_Close(qData);
end;
</syntaxhighlight>

== Endpunkt-Skript 2: <code>GET /orders/{uid}</code> (Einzel) ==

<syntaxhighlight lang="pascal">
// Derselbe Helfer wie im Listen-Skript - hier schreibt er in die WURZEL, weil
// der Auftrag selbst die Antwort ist. Eine eigene Fehlerfunktion braucht es
// nicht mehr: oWriter.Error setzt Statuscode, code, message, uid und traceId.
// Derselbe Helfer wie im Listen-Skript - hier schreibt er in die WURZEL,
// weil der Auftrag selbst die Antwort ist.
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TqSQL;
const cOffset: string);
begin
oWriter.Str ('uid' , qOrder.A2UID());
oWriter.Str ('nr' , qOrder.A2C('au_nr'));
oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
oWriter.Str ('status', qOrder.A2C('au_status'));
oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cSql : string;
qData : TqSQL;
lGefunden: Boolean;
cOffset : string;
begin
// Pfad-Parameter aus /orders/{uid}
cUid := oReader.Path('uid');
cOffset := oReader.Offset();
if (cUid = '') then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Pfad-Parameter "uid" fehlt');
exit;
end;

lGefunden := false;
cSql := 'SELECT * FROM auftraege WHERE sys_uid = ' + DB_SQLVal(cUid);
if (DB_SOpen(oDB, cSql, qData)) then begin
if (not qData.EoF) then begin
_OrderFelder(oWriter, qData, cOffset);
lGefunden := true;
end;
end;
DB_Close(qData);

if (not lGefunden) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
end;
end;
</syntaxhighlight>

== Endpunkt-Skript 3: <code>PUT /orders/{uid}/modules/{code}</code> ==

<syntaxhighlight lang="pascal">
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cCode : string;
cStatus: string;
cSql : string;
qChk : TqSQL;
xMod : TqSQL;
cModUid: string;
lOk : Boolean;
begin
// Beide Pfad-Parameter
cUid := oReader.Path('uid');
cCode := oReader.Path('code');
if (cUid = '') or (cCode = '') then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Pfad-Parameter "uid" oder "code" fehlt');
exit;
end;

// Nutzdaten kommen aus dem JSON-Body. Der Rueckgabewert sagt, ob das Feld
// ueberhaupt gesendet wurde - eine eigene Hilfsfunktion dafuer braucht es
// nicht mehr.
cStatus := '';
oReader.Str('status', cStatus);
if (cStatus = '') then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
exit;
end;

// Existenzpruefung - und zugleich der Schreib-Index. Ein SELECT auf die
// sys_uid liefert beides; ein 'SELECT *' waere hier verschenkte Arbeit.
cSql := 'SELECT sys_uid FROM auftrag_module' +
' WHERE am_auftrag = ' + DB_SQLVal(cUid) +
' AND am_code = ' + DB_SQLVal(cCode) + ' LIMIT 1';
cModUid := '';
if (DB_SOpen(oDB, cSql, qChk)) then begin
if (not qChk.EoF) then begin
cModUid := qChk.A2UID();
end;
end;
DB_Close(qChk);

if (cModUid = '') then begin
oWriter.Error(404, 'NOT_FOUND', 'Modul nicht gefunden');
exit;
end;

// Update
// Der Satz wird ueber seine sys_uid geschrieben - qSqlRead waere hier
// ein zusaetzlicher Lesezugriff, und ein unveraenderter Wert wuerde gar
// kein Write erzeugen (SaveData liefert dann False).
xMod := qSqlInit(oDB, 'auftrag_module');
xMod.qSet('sys_uid' , cModUid);
xMod.qSet('am_status', cStatus);
// Rueckgabewert auswerten - ein Schreibfehler wirft keine Exception
lOk := xMod.SaveData(UPDATE_RECORD);
qSqlFree(xMod);

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Status konnte nicht gespeichert werden');
exit;
end;

oWriter.Str('status', 'ok');
end;
</syntaxhighlight>

== Test mit curl ==

<syntaxhighlight lang="bash">
# Liste
curl -H "apikey: GEHEIM123" https://api.meinserver.de/orders

# Einzelner Auftrag (uid als Pfad-Parameter)
curl -H "apikey: GEHEIM123" https://api.meinserver.de/orders/4711

# Modul-Status aendern (uid + code als Pfad-Parameter, status im Body)
curl -X PUT \
-H "apikey: GEHEIM123" \
-H "Content-Type: application/json" \
-d '{"status":"21"}' \
https://api.meinserver.de/orders/4711/modules/A1
</syntaxhighlight>

== Was dieses Beispiel zeigt ==

* '''Eine Ressource, mehrere Pfad-Formen''' über getrennte Endpunkt-Einträge mit eigenem Skript und eigener Berechtigung.
* '''Pfad-Parameter''' werden über <code>{name}</code> im Template erfasst und im Skript mit <code>oReader.Path('name')</code> gelesen.
* Reihenfolge der Skript-Parameter: '''<code>oReader</code> zuerst, <code>oWriter</code> danach'''.
* '''Ein Helfer bekommt den Writer''' und schreibt an der Stelle hinein, an der er gerufen wird. Derselbe <code>_OrderFelder</code> bedient den Listeneintrag und die Einzelantwort - einmal in einem <code>ObjBegin('')</code>, einmal in der Wurzel.
* Präzedenz: ein statisches Segment (z. B. <code>/orders/summary</code>) hätte Vorrang vor <code>/orders/{uid}</code>.

== Siehe auch ==

* [[/OBS/Kostenpflichtige_Module/RESTServer/Endpunkte|Endpunkte]]
* [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]]

OBS/Kostenpflichtige Module/RESTServer/Beispiel3

2026-09-09T12:31:37Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 3: Datensatz anlegen mit JSON-Body=

Dieses Beispiel zeigt einen Endpunkt mit allen vier CRUD-Zugriffen (GET, POST, PUT und - anstelle von DELETE - PATCH, siehe den Hinweis beim Schliessen). Es geht um Tickets eines externen Servicedesks, der Tickets ueber den OBS REST-Server in OBS einliefern, abrufen, aktualisieren und schliessen kann.

{{Hinweis|Dieses Beispiel adressiert ein einzelnes Ticket über einen Query-Parameter (''?id...''). Alternativ lässt sich dieselbe Ressource über ein Pfad-Template wie ''/tickets/{id}'' ansprechen; die ID steht dann als ''oReader.Path('id')'' bereit. Ein vollständiges Beispiel dazu zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].}}

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'', Bindung 0.0.0.0:443
* '''Zugang:''' ''Servicedesk-X''
** API-Key: zufaellig generiert
** Host: ''servicedesk.kunde.de'' (DNS-gebunden, IP-Zugriff wird abgelehnt)
** JWT: nicht aktiv
* '''Endpunkt:''' ''tickets/v1'', Profil ''Public-API''
* '''Berechtigung:''' Zugang ''Servicedesk-X'' fuer Endpunkt ''tickets/v1'' freigeschaltet

==Endpunkt-Skript ''tickets/v1''==

<syntaxhighlight lang="pascal" line>
//------------------------------------------------------------------------------
// Hilfsprozedur: die FELDER eines Tickets. Sie bekommt den Writer und schreibt
// in das Objekt, das der Aufrufer geoeffnet hat - einmal als Listeneintrag,
// einmal in die Wurzel. Ein Helfer, der ein Fragment als String zurueckgibt,
// waere der alte Weg; dabei ging die Reihenfolge im Zusammenbau verloren.
//------------------------------------------------------------------------------

procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery;
const cOffset: string);
begin
oWriter.Str ('id' , qTicket.A2UID());
oWriter.Str ('nr' , qTicket.A2C('ti_nr'));
oWriter.Str ('betreff', qTicket.A2C('ti_betreff'));
oWriter.Str ('status' , qTicket.A2C('ti_status'));
oWriter.Str ('beschr' , qTicket.A2C('ti_beschr'));
// Zeitpunkte gehen als ISO-8601 MIT OFFSET ueber die Leitung, nicht im
// SQL-Format: DTToSQL liefert 'JJJJ-MM-TT hh:mm:ss' ohne Zeitzone, und der
// Konsument muss dann raten, in welcher er steht. RestIsoFromDate nimmt den
// Offset des Servers dazu. Ein leeres Datum ergibt null, nicht 1899.
oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset));
end;

// Fuer den Body-Zugriff und fuer Fehlerantworten braucht es keine eigenen
// Hilfsfunktionen mehr: oReader liest typisiert, oWriter.Error baut die
// vollstaendige Fehlerhuelle samt traceId.

//------------------------------------------------------------------------------
// GET /tickets/v1?id=... - einzelnes Ticket
// GET /tickets/v1 - alle offenen Tickets
//------------------------------------------------------------------------------

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
qData : TxFQuery;
cId : string;
cOffset : string;
lGefunden: Boolean;
begin
cId := oReader.Param('id');
// Der Offset des Servers geht in jeden Zeitstempel der Antwort.
cOffset := oReader.Offset();

if (not Empty(cId)) then begin
lGefunden := false;
cSql := 'SELECT * FROM tickets WHERE sys_uid = ' + DB_SQLVal(cId);
if (DB_SOpen(oDB, cSql, qData)) then begin
// EoF gehoert dazu: DB_SOpen sagt nur, dass die ABFRAGE lief.
if (not qData.EoF) then begin
_TicketFelder(oWriter, qData, cOffset);
lGefunden := true;
end;
end;
DB_Close(qData);

if (not lGefunden) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
end;
end else begin
// Die Liste ist eine nackte Liste. RootArr steht vor der Abfrage:
// kein Treffer heisst leere Liste, nicht leeres Objekt.
oWriter.RootArr();
cSql := 'SELECT * FROM tickets WHERE ti_status <> "9" ORDER BY ti_aend_dat DESC';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oWriter.ObjBegin('');
_TicketFelder(oWriter, qData, cOffset);
oWriter.ObjEnd;
qData.Next();
end;
end;
DB_Close(qData);
end;
end;

//------------------------------------------------------------------------------
// POST /tickets/v1 - neues Ticket anlegen
// Body: { "betreff":"...", "beschr":"..." }
//------------------------------------------------------------------------------

procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket : TqSQL;
cId : string;
cBetreff: string;
cBeschr : string;
lOk : Boolean;
begin
// HasBody unterscheidet "kein Koerper" von "Koerper ohne das Feld" - das
// erste ist ein 400, das zweite ein 422.
if (not oReader.HasBody()) then begin
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;

cBetreff := '';
cBeschr := '';
oReader.Str('betreff', cBetreff);
oReader.Str('beschr' , cBeschr);

if (Empty(cBetreff)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "betreff" fehlt');
exit;
end;

cId := GetNewId(oDB);

xTicket := qSqlInit(oDB, 'tickets');
xTicket.lNoSysUID := True;
try
xTicket.qSet('sys_uid' , cId);
xTicket.qSet('ti_nr' , DB_NeuNum(oDB, 'tickets', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
xTicket.qSet('ti_betreff' , cBetreff);
xTicket.qSet('ti_beschr' , cBeschr);
xTicket.qSet('ti_status' , '1');
xTicket.qSet('ti_anl_dat' , Now());
xTicket.qSet('ti_aend_dat', Now());
// SaveData liefert einen Boolean. Ein SQL-Fehler - etwa Duplicate entry
// auf einem eindeutigen Index - wirft KEINE Exception und steht in
// keinem Protokoll. Ohne diese Auswertung antwortet der Endpunkt mit
// 201, ohne etwas angelegt zu haben.
lOk := xTicket.SaveData(NEW_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht angelegt werden');
exit;
end;

oWriter.Str('id' , cId);
oWriter.Str('status', 'created');
oWriter.Status(201);
oWriter.Header('Location', '/tickets/v1?id=' + cId);
end;

//------------------------------------------------------------------------------
// PUT /tickets/v1 - Ticket aktualisieren
// Body: { "id":"...", "status":"...", "beschr":"..." }
//------------------------------------------------------------------------------

procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket: TqSQL;
lOk : Boolean;
cId : string;
cStat : string;
cBeschr: string;
begin
if (not oReader.HasBody()) then begin
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;

cId := '';
cStat := '';
cBeschr := '';
oReader.Str('id' , cId);
oReader.Str('status', cStat);
oReader.Str('beschr', cBeschr);

if (Empty(cId)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "id" fehlt');
exit;
end;

if (not DB_LSeek(oDB, 'tickets', 'sys_uid = ' + DB_SQLVal(cId))) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;

// Zum Aendern qSqlInit mit sys_uid, nicht qSqlRead: qSqlRead liest den
// Altsatz und schreibt nur Aenderungen - ein unveraenderter Wert erzeugt
// gar kein Write und SaveData liefert False.
xTicket := qSqlInit(oDB, 'tickets');
xTicket.qSet('sys_uid', cId);
try
if (not Empty(cStat)) then xTicket.qSet('ti_status' , cStat);
if (not Empty(cBeschr)) then xTicket.qSet('ti_beschr' , cBeschr);
xTicket.qSet('ti_aend_dat', Now());
lOk := xTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geaendert werden');
exit;
end;

oWriter.Str('status', 'updated');
end;

//------------------------------------------------------------------------------
// PATCH /tickets/v1?id=... - Ticket schliessen (Soft-Delete via Status=9)
//
// NICHT als DELETE: 'Delete' ist in der Skriptsprache eine Standardprozedur,
// eine eigene Prozedur dieses Namens laesst sich nicht uebersetzen. Solange das
// so ist, laeuft ein Loeschen ueber PATCH oder POST. Siehe den Hinweis unten.
//------------------------------------------------------------------------------

procedure Patch(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket: TqSQL;
cId : string;
lOk : Boolean;
begin
cId := oReader.Param('id');
if (Empty(cId)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "id" fehlt');
exit;
end;

if (not DB_LSeek(oDB, 'tickets', 'sys_uid = ' + DB_SQLVal(cId))) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;

xTicket := qSqlInit(oDB, 'tickets');
xTicket.qSet('sys_uid', cId);
try
xTicket.qSet('ti_status' , '9');
xTicket.qSet('ti_aend_dat', Now());
lOk := xTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geschlossen werden');
exit;
end;

oWriter.Str('status', 'closed');
end;
</syntaxhighlight>

{{Achtung|'''Ein DELETE-Endpunkt kann derzeit kein Skript haben.''' Der Server
ruft die Prozedur, die genauso heisst wie das HTTP-Verb - fuer DELETE also
<code>Delete</code>. Dieser Name ist in der Skriptsprache belegt
(Standardprozedur zum Loeschen aus einer Zeichenkette), und die Deklaration
laesst sich nicht uebersetzen; die Meldung nennt dabei nur die Zeile, nicht die
Ursache. Bis das geloest ist: das Loeschen als <code>PATCH</code> oder
<code>POST</code> mit einer Aktion abbilden. Das Abmelden am JWT-Endpunkt ist
davon nicht betroffen - es laeuft als DELETE '''ohne''' Skript vollstaendig in
der Engine.}}

==Aufruf mit curl==

Liste aller offenen Tickets:

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

Einzelnes Ticket:

curl -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"

Neues Ticket anlegen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"betreff\":\"Drucker offline\",\"beschr\":\"Etage 2, Raum 23\"}" ^
https://api.meinserver.de/tickets/v1

Ticket aktualisieren:

curl -X PUT -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"id\":\"abc-123\",\"status\":\"2\"}" ^
https://api.meinserver.de/tickets/v1

Ticket schliessen:

curl -X PATCH -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"

==Aufruf aus PHP==

<syntaxhighlight lang="php" line>
<?php
$apikey = '[API-KEY]';
$base = 'https://api.meinserver.de/tickets/v1';

function rest($method, $url, $apikey, $body = null) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL , $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
$headers = ['apikey: ' . $apikey];
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res, true);
}

// Neues Ticket anlegen
$neu = rest('POST', $base, $apikey, [
'betreff' => 'Drucker offline',
'beschr' => 'Etage 2, Raum 23'
]);
$id = $neu['id'];

// Status aktualisieren
rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2']);

// Liste auslesen
$alle = rest('GET', $base, $apikey);
foreach ($alle as $t) {
echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
}
?>
</syntaxhighlight>

==Was zeigt das Beispiel?==

* Saubere Trennung der CRUD-Methoden in einem Endpunkt.
* Verwendung des JSON-Body fuer komplexere Eingangsdaten (POST, PUT).
* Verwendung von Query-Parametern fuer einfache Werte (GET, PATCH).
* Soft-Delete ueber Status-Aenderung statt physischer Loeschung - und warum er als PATCH und nicht als DELETE laeuft.
* Eindeutige Audit-UIDs (''Y00CXXXXxx'') fuer jeden DB-Zugriff zur Nachvollziehbarkeit.
* Host-gebundener Zugang als zweite Sicherheitsebene neben dem API-Key.
* Alternativ: ID per Pfad-Parameter statt Query-Parameter (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4]]).

OBS/Kostenpflichtige Module/RESTServer/Beispiel5

2026-09-09T12:31:25Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz=

Dieses Beispiel zeigt einen schreibenden Endpunkt für eine mobile App: Aufträge werden mit echten HTTP-Statuscodes aktualisiert, konkurrierende Änderungen über ETag/If-Match abgesichert (Optimistic Concurrency) und doppelte Sendungen über einen Idempotency-Key abgefangen. Die Anmeldung nutzt JWT mit Custom-Claims (Mandant, Rollen) und einem Refresh-Token.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App''
** API-Key: zufällig generiert
** JWT aktiv, JWT-Endpunkt ''auth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
* '''Endpunkte''' (beide dem Profil ''Public-API'' zugeordnet):
** ''orders/{uid}'' - Auftrag lesen/Ändern
** ''orders/{uid}/material'' - Material erfassen
* '''Berechtigung:''' Zugang ''Mobile-App'' für beide Endpunkte freigeschaltet

{{Hinweis|Für das Abmelden gibt es '''keinen eigenen Endpunkt'''. Es läuft über
ein ''DELETE'' auf den JWT-Endpunkt ''auth'' und braucht daher weder eine Zeile
in ''RESTSRV_ENDPOINTS'' noch eine Berechtigung.}}

==JWT-Authentifizierungs-Skript (Zugang)==

Stellt Mandant und Rollen als Custom-Claims aus und löst über ''_OBS_JWT_REFRESH_ID'' ein Refresh-Token aus. Bei einem Refresh ruft der Server im selben Skript die Methode ''Refresh'' auf. Die Hilfsfunktionen (''PasswortPasst'', ''TechnikerMandant'', ''TechnikerRollen'', ''TechnikerAktiv'', ''AuftragLesen'', ''AuftragVersion'', ''AuftragSpeichern'', ''MaterialAnlegen'', ''ArtikelPreis'', ''PushRegistrierungLoeschen'') sind illustrativ und projektabhängig - sie stehen für Ihre Fachlogik, nicht für eine Server-API.

{{Hinweis|Eine '''eigene Sperrtabelle für Refresh-jti ist nicht nötig'''.
Einmalgebrauch, Rotation und Widerruf führt der Server in ''RESTSRV_TOKEN'' -
das Skript entscheidet nur, '''ob''' und '''mit welchen Rechten''' die Sitzung
fortgesetzt wird.}}

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
cPass: string;
begin
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

if (PasswortPasst(cUser, cPass)) then begin
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser)); // z.B. "tech,lead"
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das Refresh-Token aus
// _OBS_JWT_REFRESH_EXP weggelassen -> Default 90 Tage
end else begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Login fehlgeschlagen');
end;
end;

//------------------------------------------------------------------------------

procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
begin
cUser := oReader.Subject();

// Das vorgelegte Refresh-Token hat der Server bereits geprueft und
// entwertet. Hier wird nur entschieden, ob die Sitzung fortgesetzt
// werden darf - und mit welchen Rechten.
if (not TechnikerAktiv(cUser)) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
exit;
end;

// Mandant und Rollen NEU lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID());
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}'' - ändern mit ETag / If-Match==

''GET'' liefert den Auftrag samt ''ETag'' (Version), ''PUT'' prüft Rolle und ''If-Match''.

<syntaxhighlight lang="pascal" line>
// AuftragLesen bekommt den WRITER und schreibt die Felder des Auftrags in die
// Wurzel; nVer kommt als var-Parameter zurueck. Vorher wurde ihm das
// Antwortobjekt hineingegeben - derselbe Gedanke, nur ohne Objekt.
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
nVer: Integer;
begin
cUid := oReader.Path('uid');
if (not AuftragLesen(oWriter, oReader.Claim('tenant'), cUid, nVer)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
exit;
end;
oWriter.Header('ETag', xStr(nVer));
end;

//------------------------------------------------------------------------------

procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
nAktuell: Integer;
nIfMatch: Integer;
begin
// nur Rolle "lead" darf ändern - Rolle kommt aus dem Token, nicht aus dem Body.
// Mit Trennzeichen suchen: ein blosses Pos('lead', ...) wuerde auch in
// "leadless" oder "teamlead" treffen.
if (Pos(',lead,', ',' + oReader.Claim('roles') + ',') = 0) then begin
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Diese Rolle darf nicht aendern');
exit;
end;

cUid := oReader.Path('uid');
nAktuell := AuftragVersion(cUid);
nIfMatch := iVal(oReader.Param('if-match'));

if (nIfMatch <> nAktuell) then begin
// Der ETag gehoert AUCH an die Ablehnung - sonst kennt der Client den
// gueltigen Wert nicht und sein naechster Versuch scheitert wieder.
// Header und Error stoeren sich nicht: Error ersetzt nur den Koerper.
oWriter.Header('ETag', xStr(nAktuell));
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Auftrag wurde zwischenzeitlich geaendert');
exit;
end;

// AuftragSpeichern gibt den Rueckgabewert von SaveData durch. Ohne
// diese Pruefung antwortet der Endpunkt mit 200 und einem neuen ETag,
// obwohl nichts geschrieben wurde - siehe Scripting, Schreibfehler
// erkennen.
if (not AuftragSpeichern(cUid, oReader)) then begin // setzt Version auf nAktuell + 1
oWriter.Error(500, 'INTERNAL_ERROR', 'Der Auftrag konnte nicht gespeichert werden');
exit;
end;

oWriter.Header('ETag', xStr(nAktuell + 1));
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}/material'' - idempotentes Anlegen==

''POST'' erfasst '''mehrere''' Materialpositionen in einem Aufruf: Validierungsfehler -> 422, erfolgreiches Anlegen -> 201 mit den vergebenen Positionen.

Gegen doppelte Sendungen schickt der Client den Header ''Idempotency-Key''. '''Das
Skript muss dafür nichts tun''' - der Server erkennt den Header, merkt sich das
Ergebnis und liefert bei einer Wiederholung mit demselben Schlüssel die
gespeicherte Antwort zurück, ohne das Skript erneut zu starten (siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz). Das Skript kümmert sich nur um seine Fachlogik:

<syntaxhighlight lang="pascal" line>
// Koerper: {"positionen":[{"artikel":"4711","menge":2},
// {"artikel":"0815","menge":1}]}
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cPos : string;
cArtikel : string;
cNeueUid : string;
nMenge : Integer;
nPreis : Double;
nGesamt : Double;
nAnz : Integer;
nI : Integer;
begin
cUid := oReader.Path('uid');

// 1) Gestalt pruefen. Count liefert 0, wenn das Feld fehlt ODER keine
// Liste ist - IsArr unterscheidet die beiden Faelle. Ein Objekt, wo
// eine Liste erwartet wird, ist etwas anderes als eine leere Liste.
nAnz := oReader.Count('positionen');
if (not oReader.IsArr('positionen')) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'positionen muss eine Liste sein');
exit;
end;
if (nAnz = 0) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'positionen ist leer');
exit;
end;

// 2) ALLE Positionen pruefen, BEVOR die erste gebucht wird. Sonst
// haette ein Fehler in Position 3 zwei gebuchte Zeilen und eine
// Fehlerantwort hinterlassen - der Client wiederholt und bucht die
// ersten zwei erneut.
//
// Verschachtelung steht im Pfad: Punkt fuer Felder, eckige Klammern
// fuer Listeneintraege.
for nI := 0 to nAnz - 1 do begin
cPos := 'positionen[' + IntToStr(nI) + ']';
cArtikel := '';
nMenge := 0;
oReader.Str(cPos + '.artikel', cArtikel);
oReader.Int(cPos + '.menge' , nMenge);
if ((Empty(cArtikel)) or (nMenge <= 0)) then begin
oWriter.Error(422, 'VALIDATION_FAILED',
'Position ' + IntToStr(nI + 1) + ': artikel und menge sind Pflicht');
exit;
end;
end;

// 3) Buchen und antworten in EINEM Durchgang. Die Positionsnummern
// entstehen beim Buchen, also schreibt die Schleife sie an der Stelle,
// an die sie gehoeren - gesammelt und am Ende eingesetzt werden muss
// nichts.
nGesamt := 0;
oWriter.ArrBegin('positionen');
for nI := 0 to nAnz - 1 do begin
cPos := 'positionen[' + IntToStr(nI) + ']';
cArtikel := '';
nMenge := 0;
oReader.Str(cPos + '.artikel', cArtikel);
oReader.Int(cPos + '.menge' , nMenge);

cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);
if (Empty(cNeueUid)) then begin
// Der Stapel wird GESCHLOSSEN, bevor der Fehler gesetzt wird:
// oWriter.Error verwirft zwar den begonnenen Koerper, aber ein
// offener ArrBegin bleibt ein Strukturfehler - dann antwortet der
// Server 500 mit "Verschachtelung nicht geschlossen" statt mit
// dieser Meldung.
oWriter.ArrEnd;
oWriter.Error(500, 'INTERNAL_ERROR',
'Position ' + IntToStr(nI + 1) + ' konnte nicht gebucht werden');
exit;
end;

nPreis := ArtikelPreis(cArtikel) * nMenge;
nGesamt := nGesamt + nPreis;

oWriter.ObjBegin(''); // leerer Name = Listeneintrag
oWriter.Str('uid' , cNeueUid);
oWriter.Str('artikel', cArtikel);
oWriter.Int('menge' , nMenge);
// Zwei Nachkommastellen, immer mit Dezimalpunkt. Selbst
// formatiert stand bei Werten ab 1000 der Tausendertrenner im
// JSON - gueltiges JSON, falscher Wert, keine Meldung.
oWriter.Num('preis' , nPreis, 2);
oWriter.ObjEnd;
end;
oWriter.ArrEnd;

oWriter.Num('gesamt', nGesamt, 2);
oWriter.Status(201);
end;
</syntaxhighlight>

==Abmelden - ohne Endpunkt und ohne Skript==

Beim Abmelden soll das Gerät seine Sitzung wirklich verlieren, nicht erst mit dem
Ablauf des Tokens. Dafür ist '''nichts einzurichten''': ein ''DELETE'' auf den
JWT-Endpunkt mit dem Access-Token genügt, der Server sperrt die Sitzung in
''RESTSRV_TOKEN'' und antwortet 204.

Gesperrt wird die ganze Sitzung, also auch die Access-Token vorheriger
Erneuerungen. Ein zweiter Aufruf ist unschädlich und bleibt 204. Kann der Server
die Sitzung nicht sperren, antwortet er '''503''' mit ''Retry-After'' - die App
wiederholt den Abmeldevorgang dann.

Nur wenn beim Abmelden zusätzlich etwas passieren soll - hier: die
Geräteregistrierung für Push löschen -, braucht es einen eigenen Endpunkt. Er
erledigt seine Fachlogik und ruft ''oWriter.JwtRevoke'':

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cAlle : string;
lAlle : Boolean;
begin
PushRegistrierungLoeschen(oReader.Claim('technikerUid'));

// Optional: {"alleGeraete": true} meldet den Techniker ueberall ab.
// Diese Entscheidung gehoert bewusst in ein Skript - sie braucht eine
// Berechtigungspruefung, die der JWT-Endpunkt nicht leisten kann.
lAlle := false;
oReader.Bool('alleGeraete', lAlle);
cAlle := IIF(lAlle, 'all', 'session');

oWriter.JwtRevoke(cAlle);
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"tech1\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/auth/

{"token":"eyJ...","accessToken":"eyJ...","refreshToken":"eyJ...",
"expiresIn":3600,"serverTime":"2026-06-29T15:30:12+02:00"}

Bei falschen Zugangsdaten antwortet der Server mit '''401''' und dem Text aus dem
Authenticate-Skript als ''error.message''.

Auftrag lesen (liefert den ETag-Header):

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711
... ETag: 7

ändern mit korrektem If-Match -> 200, mit veraltetem If-Match -> 409:

curl -i -X PUT -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "If-Match: 7" -H "Content-Type: application/json" ^
-d "{\"status\":\"erledigt\"}" ^
https://api.meinserver.de/orders/4711

Material idempotent erfassen (zweiter Aufruf mit gleichem Key -> gleiche Antwort, keine Doppelbuchung):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Idempotency-Key: 9c84-7f2a-..." -H "Content-Type: application/json" ^
-d "{\"positionen\":[{\"artikel\":\"A100\",\"menge\":3},{\"artikel\":\"B200\",\"menge\":1}]}" ^
https://api.meinserver.de/orders/4711/material

Die Antwort des zweiten Aufrufs trägt zusätzlich den Header
''Idempotent-Replay: true'' - daran ist erkennbar, dass sie aus dem Speicher kam
und nichts erneut gebucht wurde.

Token erneuern (Refresh-Token im Authorization-Header an denselben JWT-Endpunkt):

curl -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer <refreshToken>" ^
https://api.meinserver.de/auth/

Die Antwort enthält ein neues Paar. Das alte Refresh-Token ist damit verbraucht:
ein zweiter Aufruf mit demselben Token antwortet '''401'''. Erfolgt er innerhalb
von 60 Sekunden, bleibt die Sitzung bestehen (paralleler Refresh der App); später
gilt er als Wiedervorlage und die '''ganze Sitzung wird gesperrt''' - der
Techniker muss sich neu anmelden, und der Vorfall steht mit IP im Protokoll.

Abmelden - DELETE auf denselben JWT-Endpunkt, Access-Token im Header:

curl -i -X DELETE -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/auth/

HTTP/1.1 204 No Content

Derselbe Token danach noch einmal verwendet:

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711

HTTP/1.1 401 Unauthorized

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00G9TOK09",
"message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden",
"traceId": "20260819T091233123-00001A"
}
}
</pre>

==Was zeigt das Beispiel?==

* Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422, 500.
* Eine '''Liste aus dem Körper lesen''' über ''oReader.Count'' und Pfade wie ''positionen[0].artikel'' - ohne Cast, ohne ''.Items[i]''.
* Eine '''benannte Liste von Objekten schreiben''' (''ArrBegin'' / ''ObjBegin('')'' / ''ArrEnd'') und '''Kommazahlen''' über ''oWriter.Num(name, wert, 2)''.
* '''Erst prüfen, dann schreiben''': Alle Positionen werden validiert, bevor die erste gebucht wird - sonst hinterlässt ein Fehler in Position 3 zwei gebuchte Zeilen und eine Fehlerantwort.
* '''Den Stapel schließen, bevor ein Fehler gesetzt wird''' - ein offener ''ArrBegin'' ist auch bei ''oWriter.Error'' ein Strukturfehler.
* Jeder Schreibzugriff wird auf Erfolg geprüft - ein gescheitertes ''SaveData'' darf nicht als 200 oder 201 beim Client ankommen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting#Schreibfehler erkennen|Schreibfehler erkennen]]).
* Optimistic Concurrency über ''ETag'' (GET) und ''If-Match'' (PUT) -> 409 VERSION_CONFLICT.
* Idempotente Schreibzugriffe über den ''Idempotency-Key'' - '''vom Server erledigt''', das Skript enthält dafür keine Zeile Code.
* Rollenprüfung aus dem Token-Claim über ''oReader.Claim('roles')'', nicht aus dem Body.
* JWT mit Custom-Claims (''tenant''/''roles'') und Refresh-Token mit Rotation - '''vom Server erledigt''', das Skript führt keine Sperrtabelle.
* Anmelden, Erneuern und Abmelden über '''einen''' Endpunkt - Abmelden als ''DELETE'', ohne eigene Endpunkt-Zeile und ohne Skript.
* ''oWriter.JwtRevoke'' für den Fall, dass beim Abmelden zusätzlich Fachlogik laufen soll oder alle Geräte gemeint sind.
* ''traceId'' im Fehler-Body für die Support-Nachverfolgung (auch als Header ''X-Trace-Id'').

OBS/Kostenpflichtige Module/RESTServer/Scripting

2026-09-09T12:31:08Z

Rademacker:

{{Kostenpflichtige Module}}

=Anleitung für Endpunkt-Skripte=

Jede Anfrage an einen Endpunkt wird nach erfolgreicher Authentifizierung und Autorisierung an das hinterlegte Skript weitergegeben. Das Skript ist in Object Pascal geschrieben und greift auf die OBS-Bibliothek (DB-Zugriff, Hilfsfunktionen) zu.

==Sicherheitshinweise==

{{Hinweis|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Übergabeparameter dürfen niemals ungeprüft in SQL-Anweisungen eingebaut werden. Werte immer über ''DB_SQLVal'' bzw. Parameter-Bindings absichern, Eingabewerte gegen Whitelists prüfen.}}

* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
* Nur das zurückgeben, was der Konsument wirklich braucht - keine internen IDs, keine Sys-Felder, keine Passwörter.
* Bei Fehlern keine internen Details an den Konsumenten zurückgeben; stattdessen schreibt der Server ohnehin Detail-Einträge in '''RESTSRV_PROTO'''.

==Methoden-Signatur==

Pro HTTP-Methode wird im Skript eine gleichnamige '''Prozedur''' implementiert. Der Server ruft genau die Prozedur auf, die zur Methode des eingehenden Requests passt.

procedure Get (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Patch (oReader: TxRestReader; oWriter: TxRestWriter);

Zwei Handles, kein Rückgabewert: '''oReader''' ist die Anfrage, '''oWriter''' die
Antwort. Beide erzeugt der Server, beide gehören ihm - im Skript wird nichts
angelegt und nichts freigegeben.

{{Achtung|'''DELETE hat keine Skript-Methode.''' <code>Delete</code> ist in der
Skriptsprache eine Standardprozedur (Löschen aus einer Zeichenkette); eine eigene
Prozedur dieses Namens lässt sich nicht übersetzen, und der Fehler nennt nur die
Zeile der Deklaration. Wer einen DELETE-Endpunkt braucht, legt die Methode unter
einem anderen Verb ab oder trennt sie in ein eigenes Skript.}}

Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
Not Allowed''' (<code>METHOD_NOT_ALLOWED</code>) und nennt im Header
<code>Allow</code> die Verben, die dieses Skript tatsächlich anbietet - die Liste
stammt aus dem kompilierten Skript und kann deshalb nicht veralten:

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT

Ein im Vertrag zugesagtes Verb braucht also seine Prozedur. Fehlt sie, ist das an
der Antwort sofort zu erkennen und '''kein''' Serverfehler.

==Die Anfrage lesen: oReader==

''oReader'' ist der einzige Zugang zur Anfrage - Query, Header, Formularfelder,
Pfadwerte, Token-Claims und Körper. Alles davon sind '''Zeichenketten''' oder
werden über einen typisierten Leser geholt.

{| class="wikitable"
! Aufruf !! Was er liefert
|-
| <code>oReader.Param('kundennr')</code> || Query-Parameter, POST-Parameter (form-urlencoded) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet
|-
| <code>oReader.Path('uid')</code> || Wert eines Platzhalters aus dem Pfad-Template
|-
| <code>oReader.Form('bemerkung')</code> || Formularfeld einer <code>multipart/form-data</code>-Übertragung
|-
| <code>oReader.Claim('tenant')</code> || Custom-Claim des vorgelegten Tokens
|-
| <code>oReader.Subject()</code> || Subject des Tokens (''sub''-Claim)
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests
|-
| <code>oReader.Offset()</code> || UTC-Offset des Servers, z.B. ''+02:00''
|-
| <code>oReader.HasBody()</code> || Wurde überhaupt ein JSON-Körper gesendet?
|}

Filterung durch den Server:

* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
* Werte, die von aussen kommen, können die reservierten Namen nicht besetzen.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.

Zugriff im Skript:

cKundenNr := oReader.Param('kundennr');
if (not Empty(cKundenNr)) then begin
// ...
end;

===Der Körper: Zugriff über Pfade===

Den JSON-Körper liest ''oReader'' über '''Pfade'''. Es gibt keine Unterobjekte im
Skript, keinen Cast, kein ''.Items[i]'' - und damit auch keine Lebensdauer, um die
sich jemand kümmern müsste.

{| class="wikitable"
! Aufruf !! Bedeutung
|-
| <code>oReader.Str('betreff', cWert)</code> || Liest den Wert. '''Rückgabe Boolean''': war das Feld da? Fehlt es, bleibt die Variable unverändert
|-
| <code>oReader.Int('menge', nWert)</code> || dito, Ganzzahl
|-
| <code>oReader.Num('preis', nWert)</code> || dito, Kommazahl. '''Der Dezimalpunkt aus JSON wird richtig gelesen''' - kein ''StrTran'' mehr
|-
| <code>oReader.Bool('aktiv', lWert)</code> || dito, Boolean
|-
| <code>oReader.NumDef('rabatt', nWert, 0)</code> || wie ''Num'', mit Vorgabewert
|-
| <code>oReader.Has('feld')</code> || Ist das Feld vorhanden? (auch bei ''null'')
|-
| <code>oReader.Count('zeiten')</code> || Anzahl Einträge einer Liste, 0 wenn keine Liste
|-
| <code>oReader.IsArr('zeiten')</code> / <code>IsObj('zeiten[0]')</code> || Gestalt prüfen
|-
| <code>oReader.Keys()</code> || Alle Feldnamen der obersten Ebene, in Kommas eingefasst
|}

'''Verschachtelung steht im Pfad''' - Punkt für Felder, eckige Klammern für Listen:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cVon : string;
nAnz : Integer;
nI : Integer;
begin
nAnz := oReader.Count('zeiten');
for nI := 0 to nAnz - 1 do begin
if (oReader.Str('zeiten[' + IntToStr(nI) + '].von', cVon)) then begin
// ... cVon verarbeiten ...
end;
end;
end;
</syntaxhighlight>

{{Hinweis|'''Der Rückgabewert unterscheidet „nicht gesendet" von „leer
gesendet".''' <code>oReader.Str('feld', cWert)</code> liefert bei
<code>"feld": null</code> ''true'' mit leerem Wert und bei fehlendem Feld
''false''. Genau diese Unterscheidung braucht ein PATCH-artiger Aufruf: „Feld
löschen" und „Feld nicht anfassen" sehen sonst gleich aus.}}

Ist gar kein Körper gesendet worden, liefert jeder Leser ''false'' und
''HasBody()'' ist ''false''. Maximale Body-Grösse: 10 MB.

===Werte des Servers===

Bei aktiver JWT-Authentifizierung stehen die Token-Claims über den Reader zur
Verfügung. Sie tragen intern weiterhin die Namen mit Präfix '''_OBS_''' - im
Skript werden sie aber über die Zugriffe der Tabelle oben gelesen und nicht mehr
über den Namen:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_JWT_ID')</code> || JWT-Id (''jti''-Claim) - typisch die User-Id. '''Muss nicht eindeutig sein''': die Sitzung führt der Server über eigene Kennungen (siehe unten)
|-
| <code>oReader.Subject()</code> || Subject (''sub''-Claim) - typisch Benutzername
|-
| <code>oReader.Param('_OBS_JWT_AUDIENCE')</code> || Audience (''aud''-Claim) - typisch Mandant / Rolle
|-
| <code>oReader.Claim('tenant')</code> || Beliebiger Custom-Claim des Tokens, hier ''tenant''; im Folge-Skript lesbar
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}

Unabhängig von JWT stehen ausserdem immer zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_SERVER_TIME')</code> || Aktuelle Serverzeit als ISO-8601 '''mit UTC-Offset''' (z.B. ''2026-08-17T09:12:33+02:00''). Nützlich, um Datumswerte in derselben Zeitzone auszuliefern, in der der Server arbeitet, und damit ein Client seinen Uhren-Versatz bestimmen kann
|-
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+02:00''. Er geht in die Zeitfunktionen (siehe [[#Zeitangaben auf der Leitung|Zeitangaben]])
|-
| <code>oReader.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden (''JWT-Exp'' × 60). Damit kann ein Konfigurations-Endpunkt denselben Wert ausliefern, den der Token wirklich hat
|}

Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.

Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
''oReader.Claim('sid')'' und ''oReader.Claim('rid')'':

{| class="wikitable"
! Claim !! Inhalt
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
|}

Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Skripts gesetzt - ein Skript kann sie also auch mit einem eigenen Claim ''sid''
nicht überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.

===Pfad-Parameter===

Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte über ''oReader.Path'' bereit:

{| class="wikitable"
! Template !! Zugriff im Skript
|-
| <code>/orders/{uid}</code> || <code>oReader.Path('uid')</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>oReader.Path('uid')</code>, <code>oReader.Path('code')</code>
|}

Diese Werte kommen aus dem Routing und sind durch den Client nicht fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].

===Datei-Uploads===

Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), nimmt der Server
hochgeladene Dateien entgegen, legt sie in einem temporären Verzeichnis ab und
übergibt dem Skript Pfad, Originalname und Content-Type über den Reader. Das
Skript entscheidet selbst über die weitere Verarbeitung (z.B. DMS-Ablage). Der
Body wird in diesem Fall '''nicht''' als JSON geparst - ''oReader.HasBody()'' ist
''false''. Es gilt nicht das JSON-Body-Limit (10 MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25 MB;
Überschreitung -> 413).

'''Wie die Datei übertragen wurde, spielt für das Skript keine Rolle.''' Beide
Wege - <code>multipart/form-data</code> und der resumable
<code>Content-Range</code>-Upload - liefern dieselben vier Werte. Das
Übertragungsprotokoll samt Header, Statuscodes und Resume-Verhalten steht in
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]:

{| class="wikitable"
! Aufruf !! Inhalt
|-
| <code>oReader.UploadPath()</code> || Vollständiger Pfad zur temporären Datei auf dem Server
|-
| <code>oReader.UploadName()</code> || Originaldateiname
|-
| <code>oReader.UploadType()</code> || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt), kleingeschrieben
|-
| <code>oReader.UploadSha()</code> || SHA-256 der '''gespeicherten''' Datei, hex in Kleinbuchstaben. Damit lässt sich eine vom Client mitgesendete Prüfsumme vergleichen - erst dieser Vergleich macht aus ihr eine Zusicherung
|}

Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''UploadPath()'' und ''UploadName()'' gefüllt
sind, sobald es läuft.

{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}

Zusatzangaben, die im selben Aufruf mitkommen, liest das Skript mit
<code>oReader.Form('<name>')</code> - bei <code>multipart/form-data</code> sind
das die Partien ohne <code>filename=</code>. Ein vollständiges Beispiel zeigt
[[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].

==Die Antwort schreiben: oWriter==

Der Writer schreibt '''sequentiell''': jeder Aufruf hängt ein Feld an, an der
Stelle, an der er steht. Die äussere Klammer der Antwort setzt der Server. Wird
nichts geschrieben, antwortet er mit ''{}''. Content-Type ist
''application/json; charset=utf-8'', der Status 200, sofern das Skript nichts
anderes setzt.

Einfaches Beispiel:

<syntaxhighlight lang="pascal" line>
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
oWriter.Str('wert_string', '123');
oWriter.Int('wert_int' , 456);
end;
</syntaxhighlight>

{| class="wikitable"
! Aufruf !! Ergebnis
|-
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert
|-
| <code>oWriter.StrN('name', cWert)</code> || wie ''Str'', aber '''null''' statt einer leeren Zeichenkette
|-
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl
|-
| <code>oWriter.Num('preis', nWert, 2)</code> || Kommazahl mit fester Stellenzahl. '''Immer mit Dezimalpunkt''', unabhängig von der Locale des Servers
|-
| <code>oWriter.Bool('aktiv', lWert)</code> || ''true'' / ''false''
|-
| <code>oWriter.Null('lat')</code> || ausdrücklich ''null''
|-
| <code>oWriter.ObjBegin('kunde')</code> … <code>oWriter.ObjEnd</code> || Unterobjekt
|-
| <code>oWriter.ArrBegin('dateien')</code> … <code>oWriter.ArrEnd</code> || Liste
|-
| <code>oWriter.RootArr()</code> || Die '''Wurzel''' ist eine Liste statt eines Objekts. Muss vor dem ersten Feld stehen; ein ''ArrEnd'' gibt es dazu nicht
|-
| <code>oWriter.Raw('meta', cJson')</code> || Fertiges JSON-Fragment einbetten. Siehe unten
|}

'''In einer Liste hat ein Eintrag keinen Namen''' - der leere Feldname ist genau
das:

<syntaxhighlight lang="pascal" line>
oWriter.ArrBegin('dateien');
while (not q.EoF) do begin
oWriter.ObjBegin('');
oWriter.Str ('uid' , q.A2C('f_uid'));
oWriter.Int ('bytes' , q.A2I('f_bytes'));
oWriter.StrN('kategorie', AllTrim(q.A2C('f_kat'))); // null wenn leer
oWriter.ObjEnd;
q.Next();
end;
oWriter.ArrEnd;
</syntaxhighlight>

Ein Name in einer Liste und ein fehlender Name in einem Objekt sind beides
'''Strukturfehler'''. Der Server antwortet dann mit '''500''' und nennt die
Stelle im Protokoll - er liefert kein halbes JSON aus. Dasselbe gilt für einen
Stapel, der am Ende der Methode noch offen ist.

{{Hinweis|'''Ein Helfer bekommt den Writer als Parameter''' und schreibt an der
Stelle hinein, an der er aufgerufen wird - er gibt kein Fragment zurück. Damit
steht die Reihenfolge der Antwort im Code und nicht im Zusammenbau:

<code>procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);</code>}}

'''Raw ist der Notausgang und prüft.''' Er parst das Fragment und bettet den
'''Originaltext''' ein; ungültiges JSON gibt einen Serverfehler, der das Feld
nennt. Gebraucht wird er für ein gespeichertes, '''signiertes''' Dokument:
Parsen und Neuserialisieren würde die signierte Feldreihenfolge zerstören.

===Zeitangaben auf der Leitung===

Zeitstempel gehen als '''ISO-8601 mit Offset''' über die Leitung. Die Wandlung
gehört nicht ins Skript - dort saß der Fehler „zwei Stunden zu früh" an drei
Stellen gleichzeitig:

{| class="wikitable"
! Aufruf !! Zweck
|-
| <code>RestIsoFromDate(dWert, cOffset)</code> || OBS-Zeitpunkt -> ''2026-09-09T14:12:00+02:00''. Leerer String bei leerem Datum
|-
| <code>RestDateFromIso(cWert, cOffset)</code> || ISO-Zeichenkette -> OBS-Zeitpunkt in '''Ortszeit des Servers'''
|-
| <code>oReader.Offset()</code> || Der Offset, der in beide hineingeht
|-
| <code>RestOffsetToMinutes(cOffset)</code> || Offset in Minuten, für eigene Rechnungen
|}

==Antwort steuern: Statuscode, Header, traceId==

Statuscode, Header und das Sperren einer Sitzung laufen über eigene Aufrufe des
Writers, '''nicht''' über Felder im Körper.

{| class="wikitable"
! Aufruf !! Wirkung
|-
| <code>oWriter.Status(201)</code> || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200
|-
| <code>oWriter.Header('ETag', '7')</code> || Beliebiger Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen und Werten werden entfernt (Schutz vor Header-Injection)
|-
| <code>oWriter.NoBody()</code> || Kein Körper - für '''204'''
|-
| <code>oWriter.JwtRevoke('session')</code> || Sperrt die Sitzung des vorgelegten Tokens (''session'') oder alle Sitzungen des Subjects (''all''). Damit wird ein Endpunkt zum Logout, ohne eigene Verwaltung. Scheitert das Sperren, antwortet der Server mit '''503''' statt mit der Antwort des Skripts - siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Abschnitt Abmelden
|-
| <code>oWriter.Error(422, 'VALIDATION_FAILED', 'Feld „menge" fehlt')</code> || Fertige Fehlerantwort in der Form des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]]
|-
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer? Für einen Verteiler, der danach noch etwas anhängen will
|}

Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oReader.TraceId()'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

===Beispiel: Anlegen mit 201, Location und ETag===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueUid: string;
begin
// ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...

oWriter.Str('uid', cNeueUid);
oWriter.Status(201);
oWriter.Header('Location', '/v1/orders/' + cNeueUid);
oWriter.Header('ETag' , '1');
end;
</syntaxhighlight>

===Beispiel: Strukturierter Fehler mit Statuscode und traceId===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var nMenge: Integer;
begin
if (not oReader.Int('menge', nMenge)) then begin
// Statuscode, code, message, uid und traceId in EINEM Aufruf - dieselbe
// Huelle, die auch die Server-eigenen Fehler tragen.
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

===Beispiel: Optimistic Concurrency (ETag / If-Match)===

Mit Statuscode, Headern und dem lesbaren Header ''If-Match'' führt das Skript je Datensatz einen Versionszähler und lehnt veraltete Schreibzugriffe mit 409 ab:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var nAktuell: Integer;
nIfMatch: Integer;
begin
nAktuell := AuftragVersion(oReader.Path('uid'));
nIfMatch := iVal(oReader.Param('if-match'));

if (nIfMatch <> nAktuell) then begin
// Der ETag gehoert AUCH an die Ablehnung - sonst kennt der Client den
// gueltigen Wert nicht und sein naechster Versuch scheitert wieder.
oWriter.Header('ETag', xStr(nAktuell));
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geaendert');
exit;
end;

// ... speichern, Version hochzählen ...
oWriter.Header('ETag', xStr(nAktuell + 1));
end;
</syntaxhighlight>

==Idempotenz - was das Skript beachten muss==

Sendet ein Konsument bei ''POST''/''PUT''/''PATCH''/''DELETE'' den Header
<code>Idempotency-Key</code>, fängt der '''Server''' doppelte Sendungen ab. Das
Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine
Prüfung am Anfang der Methode.

Was das Skript wissen muss:

{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
|-
| '''2xx''' || Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
|-
| '''5xx''' oder Exception || Der Schlüssel bleibt belegt, der Fall wird protokolliert. Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist
|}

Daraus folgen zwei Regeln für Endpunkt-Skripte:

* '''Fachliche Ablehnungen als 4xx melden''' (422, 409, 404), nicht als 2xx mit Fehlertext im Body. Sonst wird die Ablehnung gespeichert und der Konsument bekommt sie bei jedem weiteren Versuch erneut - auch nachdem er den Fehler behoben hat.
* '''Die Antwort muss vollständig sein.''' Was zurückgegeben wird, wird eingefroren. Ein Feld, das erst der zweite Aufruf ergänzen würde, kommt beim Konsumenten nie an.

Der vollständige Ablauf und die Statuscodes stehen unter
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==JWT-Authentifizierungs-Skript==

Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
cPass: string;
begin
// Eingangsdaten lesen
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

// Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
if (PasswortPasst(cUser, cPass)) then begin
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_AUDIENCE', 'mandant1');
end else begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Login fehlgeschlagen');
end;
end;
</syntaxhighlight>

{{Hinweis|'''Im Anmeldeskript bleiben die _OBS_JWT_*-Felder Felder der
Antwort''' - anders als Status und Header, die zu Aufrufen des Writers geworden
sind. Der Grund: die Token-Ausstellung liest sie aus dem fertigen Körper, und
genau dort erwartet sie sie. Geschrieben werden sie deshalb wie jedes andere
Feld, nur eben mit dem Writer.}}

Rückgabewerte:

{| class="wikitable"
! status !! Bedeutung
|-
| 1 || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
|-
| 9 || Misserfolg, der Server antwortet mit '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
|}

{{Hinweis|Der Text aus ''error'' geht bei ''status'' = 9 '''an den Konsumenten'''
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Endanwender verständlich sein und keine internen Details verraten.}}

Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
„Passwort falsch" erscheinen.

Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.

===Aufbau der Token-Antwort===

Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
Feldern, die das Skript zurückgibt''':

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...",
"accessToken": "eyJ...",
"refreshToken":"eyJ...",
"expiresIn": 28800,
"serverTime": "2026-08-17T09:12:33+02:00"}

{| class="wikitable"
! Feld !! Herkunft
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
|-
| serverTime || Serverzeit ISO-8601 mit Offset
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
|}

Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.

===Custom-Claims, serverTime und Refresh===

Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:

{| class="wikitable"
! RÜckgabefeld !! Bedeutung
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als <code>oReader.Claim('<name>')</code>.
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
|}

Jedes Token trägt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh'') sowie die Sitzungskennungen ''sid'' und ''rid'' des Servers. Die Antwort enthält bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusätzlich ''refreshToken'':

{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}

{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''oReader.Claim(…)''), nie aus Body oder Query.}}

====Refresh-Methode====

Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
(Signatur, Ablauf, ''token_use=refresh'') und in der Sitzung '''entwertet'''.
Einmalgebrauch, Rotation und Sperrliste sind damit Sache des Servers. Das Skript
liefert nur noch die aktuellen Claims - genau das ist der Sinn des Aufrufs: eine
zwischenzeitlich geänderte Rolle oder ein gewechselter Mandant wirken spätestens
mit der nächsten Erneuerung.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal - einmal im Skript, einmal im
Server - und riskiert, dass beide Seiten unterschiedlicher Meinung sind. Der
Server sieht die Skript-Tabelle nicht, und das Skript sieht die Sitzung nicht.}}

Ein bereits benutztes Refresh-Token wird mit '''401''' abgelehnt. Erfolgt die
erneute Vorlage innerhalb von 60 Sekunden, bleibt die Sitzung bestehen (paralleler
Refresh einer App); danach gilt sie als Wiedervorlage und die '''gesamte Sitzung
wird gesperrt'''. Details in [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

Das alte Refresh-jti steht weiterhin als ''oReader.Param('_OBS_JWT_ID')'' bereit,
falls das Skript es für eigene Protokollierung braucht.

<syntaxhighlight lang="pascal" line>
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
begin
cUser := oReader.Subject();

// Der Server hat das vorgelegte Refresh-Token bereits geprueft und
// entwertet. Hier wird nur entschieden, ob der Benutzer die Sitzung
// fortsetzen darf - und mit welchen Rechten.
if (not BenutzerAktiv(cUser)) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
exit;
end;

// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das neue Refresh-Token aus
end;
</syntaxhighlight>

===Abmelden (Logout)===

'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Phase 4.

Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
'''gewöhnlichen Endpunkt''' und setzt dort ''_OBS_JWT_REVOKE''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
GeraeteRegistrierungLoeschen(oReader.Subject());

// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('session');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
abgemeldet, während sein Token weiterläuft.

==Fehlerbehandlung im Skript==

Tritt im Skript eine Exception auf oder schlägt die Syntax-Prüfung fehl, antwortet der Server mit 500 ''Interner Fehler'' und protokolliert die Detail-Meldung in '''RESTSRV_PROTO''' (mit Skript-Fehlertext). Der Konsument sieht keine internen Details.

Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Für einen spezifischen Fehler an den Konsumenten gibt es '''einen''' Aufruf. Er
baut dieselbe Hülle, die auch die Server-eigenen Fehler tragen - Statuscode,
''code'', ''message'', ''uid'' und ''traceId'' -, sodass beide Wege nicht
auseinanderlaufen können:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
if (Empty(oReader.Param('kundennr'))) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

{{Hinweis|'''Error verwirft einen schon begonnenen Körper''' und setzt seinen
eigenen. Ein Skript darf also getrost Felder schreiben und danach noch
abbrechen - was der Client sieht, ist die Fehlerantwort. Nur ein '''offener
Stapel''' (ein ''ObjBegin'' ohne ''ObjEnd'') bleibt auch dann ein Strukturfehler.}}

{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
Body auszuwerten - und nur so gibt der Server einen belegten
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}

===Ändern: qSqlInit statt qSqlRead===

Zum '''Ändern''' eines vorhandenen Satzes wird ebenfalls <code>qSqlInit</code>
benutzt - der Satz wird über <code>sys_uid</code> adressiert:

<syntaxhighlight lang="pascal" line>
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cSysUid); // Schreib-Index auf den Originalsatz
q.qSet('ti_status', '9');
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln, siehe unten
end;
qSqlFree(q);
</syntaxhighlight>

<code>qSqlRead</code> ist dafür die falsche Wahl, aus zwei Gründen:

* Es liest den '''kompletten Altsatz''' ein - ein zusätzlicher Lesezugriff, der Zeit kostet.
* Es schreibt anschliessend nur die '''Änderungen'''. Ist der neue Wert gleich dem alten, entsteht gar kein Write, und <code>SaveData</code> liefert '''False''' - ununterscheidbar von einem echten Fehlschlag.

{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen'''
Datensatz an, statt den vorhandenen zu ändern. Die <code>sys_uid</code> ist der
Schreib-Index und gehört bei jeder Änderung gesetzt.}}

Damit entfällt auch das übliche Paar aus <code>DB_LSeek</code> und
<code>qSqlRead</code>: '''eine''' Abfrage auf die <code>sys_uid</code> liefert
zugleich die Existenzprüfung und den Schreib-Index.

<syntaxhighlight lang="pascal" line>
cUid := '';
if (DB_SOpen(oDB, 'SELECT sys_uid FROM tickets WHERE ' + cWhere + ' LIMIT 1', q)) then begin
if (not q.EoF) then begin
cUid := q.A2UID();
end;
end;
DB_Close(q);

if (not Empty(cUid)) then begin
// ändern: qSqlInit + sys_uid
end else begin
// anlegen: qSqlInit ohne sys_uid
end;
</syntaxhighlight>

===Mehrere Felder sind EIN Schreibvorgang===

Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> entgegen
und schreibt sie mit '''einem''' <code>SaveData</code>. Fallen an derselben
Zeile mehrere Felder an, gehören sie in dasselbe Objekt:

<syntaxhighlight lang="pascal" line>
// FALSCH: fünf Felder, fünf Schreibvorgänge - und jeder Setzer, der sich
// seine sys_uid selbst holt, bringt zusätzlich eine eigene Abfrage mit
FeldSetzen(cUid, 'ti_status' , '9');
FeldSetzen(cUid, 'ti_grund' , cGrund);
FeldSetzen(cUid, 'ti_von' , cBenutzer);

// RICHTIG: ein Schreibobjekt, ein SaveData
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cUid);
q.qSet('ti_status', '9');
q.qSet('ti_grund' , cGrund);
q.qSet('ti_von' , cBenutzer);
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln
end;
qSqlFree(q);
</syntaxhighlight>

Das ist nicht nur eine Frage der Geschwindigkeit: einzeln geschriebene Felder
sind '''nicht atomar'''. Bricht der dritte Schreibvorgang ab, steht die Zeile
halb geändert da - Grund gesetzt, Zeitpunkt nicht.

Wird nichts gesetzt, darf auch nicht geschrieben werden: das Schreibobjekt dann
mit <code>qSqlFree</code> freigeben, statt ein leeres <code>SaveData</code>
abzusetzen.

{{Hinweis|Ein Setzer für '''ein''' Feld (<code>FeldSetzen(cUid, cFeld, cWert)</code>)
ist bequem und deshalb verführerisch. Er versteckt aber je Aufruf eine eigene
Abfrage und ein eigenes <code>SaveData</code>. Für einen Vorgang mit mehreren
Feldern gehört ein '''Editier-Helfer''' her, der das Schreibobjekt liefert -
geschrieben wird einmal am Ende.}}

===Keine Abfrage je Zeile===

Was in einer Liste je Zeile nachgeschlagen wird, kostet '''N''' Abfragen für
'''eine''' Antwort. Bei fünfzig Aufträgen sind das fünfzig Abfragen für ein
einziges Feld. Der Ausweg ist immer derselbe:

* Werte aus einer 1:1-Beziehung über einen <code>LEFT JOIN</code> mitnehmen - bei einem '''eindeutigen''' Index auf dem Join-Feld kann er die Zeilen nicht vervielfachen.
* Einzelwerte aus einer 1:n-Beziehung über eine '''Unterabfrage''' in der SELECT-Liste holen, nicht über einen Join (der Join würde die Zeilen vervielfachen).
* Eine echte Unterliste (Positionen, Dateien) nur dann nachladen, wenn ein '''Zählfeld''' in der Hauptabfrage sagt, dass es überhaupt eine gibt.

{{Hinweis|Ein GET soll '''lesen'''. Schreibvorgänge im Lesepfad - etwas
"beim ersten Ausliefern festschreiben" - vervielfachen sich mit der Zeilenzahl
und treffen den Aufrufer, der nur eine Liste angefordert hat.}}

===Schreibfehler erkennen===

'''<code>SaveData</code> liefert einen Boolean - und der ist die einzige
Fehlermeldung, die es gibt.''' (Auch der '''Parameter''' ist ein Boolean:
''NEW_RECORD'' und ''UPDATE_RECORD'' sind Wahrheitswerte, keine Zahlen.) Schlägt das Schreiben in der Datenbank fehl
(''Duplicate entry'' auf einem eindeutigen Index, zu langer Wert, fehlende
Spalte), dann

* wird '''keine''' Exception ausgelöst,
* steht '''nichts''' in ''RESTSRV_PROTO'',
* läuft das Skript weiter und antwortet mit dem Erfolg, den es selbst formuliert.

Wer den Aufruf als Anweisung schreibt, baut damit einen stillen Datenverlust ein.
Weil in einem Endpunkt schnell ein Dutzend Schreibvorgänge zusammenkommen, gehört
die Prüfung in eine eigene kleine Prozedur - am besten in die gemeinsame Lib:

<syntaxhighlight lang="pascal" line>
procedure Speichern(q: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
begin
lOk := q.SaveData(lNeu);
qSqlFree(q); // auch im Fehlerfall freigeben
if (not lOk) then begin
raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
end;
end;

// Aufruf statt SaveData + qSqlFree:
q := qSqlInit(oDB, 'tickets');
q.qSet('ti_betreff', cBetreff);
Speichern(q, NEW_RECORD, 'Ticket');
</syntaxhighlight>

Die Exception fängt der Server: er schreibt ''Schreiben fehlgeschlagen: Ticket''
nach '''RESTSRV_PROTO''' und antwortet mit '''500'''. Liegt ein
''Idempotency-Key'' an, wird er dabei '''freigegeben''' - die Anfrage ist also
wiederholbar (siehe Abschnitt Idempotenz).

{{Hinweis|Ein fehlgeschlagenes Schreiben ist kein Fall, in dem ein Endpunkt
sinnvoll weiterlaufen kann: die Fachwirkung ist dann unvollständig. Wer trotzdem
weitermachen will - etwa weil mehrere unabhängige Sätze geschrieben werden -,
prüft den Rückgabewert und baut selbst eine Antwort. Ignorieren darf man ihn
nie.}}

Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.

==Gemeinsamen Code auslagern==

Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:

<pre>
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</pre>

{| class="wikitable"
! Attribut !! Bedeutung
|-
| '''T''' || Tabelle, aus der geladen wird
|-
| '''I''' || Spalte, über die gesucht wird
|-
| '''V''' || Wert, der in dieser Spalte stehen muss
|-
| '''F''' || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}

Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Compiler sieht danach den zusammengesetzten Text - eine Funktion aus der Lib lässt
sich also aufrufen wie eine im Skript selbst geschriebene.

===Bewährtes Muster: Lib als eigene Endpunkt-Zeile===

Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
RESTSRV_ENDPOINTS''' abzulegen:

# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
# Den Lib-Quelltext ins Skript-Feld dieser Zeile schreiben (F7).
# '''Keine Berechtigung''' in der Berechtigungs-Liste vergeben - das ist der Schutz: ohne Berechtigung beantwortet der Server einen Aufruf mit 403.
# In jedem nutzenden Endpunkt die Direktive oben einfügen.

Damit ist die Lib reiner Ablageort und von aussen nicht nutzbar. Eine Änderung
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
angefasst werden muss.

{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Funktion hinzu, genügt es nicht, nur das nutzende Skript zu aktualisieren. Eine
ältere Lib lädt fehlerfrei - der Compiler meldet dann ausschliesslich die neuen
Namen als ''Unknown name'', was leicht wie ein Fehler im Skript aussieht.}}

{{Hinweis|Auch hier greift der Endpunkt-Cache: eine Änderung an der Lib wird erst
nach Ablauf des TTL (bis zu 60 Sekunden) wirksam.}}

===Wohin gehört welcher Code?===

Drei Ebenen, und die Zuordnung entscheidet, wie schnell eine Änderung wirkt:

{| class="wikitable"
! Art des Codes !! Wohin !! Wirksam
|-
| Fachlogik **einer** Anwendung - Feldnamen, Zustandswerte, Rollenregeln, Schreibziele || in die '''DWS-Lib dieser Anwendung''' (eigene Endpunkt-Zeile, per <code>{$L …}</code> eingebunden) || nach Ablauf des Cache-TTL, ohne Build
|-
| Mechanik, die '''mehrere''' Anwendungen brauchen - und auch das OBS-Umfeld || nach '''obs_lib''' als Delphi-Unit || erst nach Build und Rollout
|-
| Mechanik, die '''nur''' der REST-Server braucht || in die Units des Servers || erst nach Build und Rollout
|}

Die Regel hat einen praktischen Grund und keinen ästhetischen: Fachlogik ändert
sich in Tagen, Mechanik in Monaten. Was in der Lib liegt, ist nach einer Minute
aktiv; was in einer Unit liegt, braucht einen Build. Wer Fachlogik nach unten
schiebt, tauscht Geschwindigkeit gegen nichts ein.

{{Hinweis|Eine Anwendung, die ihre eigene Lib hat, kopiert sie '''nicht''' von
einer anderen. Zwei Kopien derselben Lib driften auseinander, und die Abweichung
fällt erst auf, wenn eine der beiden Anwendungen etwas Falsches tut. Geteiltes
gehört eine Ebene tiefer.}}

==Fallstricke im Skript==

Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:

{| class="wikitable"
! Stolperstein !! Richtig
|-
| ''DB_SOpen('Y00…', oDB, …)'' - der AD-UID-Parameter aus dem Delphi-Code || Im Skript '''ohne UID''': <code>DB_SOpen(oDB, cSql, q)</code>. Gleiches gilt für <code>qSqlInit(oDB, 'tab')</code> und <code>qSqlRead(oDB, 'tab', cWhere)</code> - jede dieser Funktionen beginnt mit ''oDB''
|-
| ''oReader.Str<T>(…)'' oder irgendein Generic || Generics gibt es in der Skriptsprache nicht. Die Leser sind je Typ eigene Methoden: ''Str'', ''Int'', ''Num'', ''Bool''
|-
| Eine eigene Prozedur ''Delete'' für DELETE || ''Delete'' ist eine '''Standardprozedur''' der Sprache. Die Deklaration lässt sich nicht übersetzen, und die Meldung nennt nur die Zeile - nicht die Ursache
|-
| Ein Helfer, der ein JSON-Fragment als String zurückgibt || Den '''Writer als Parameter''' übergeben und an der richtigen Stelle hineinschreiben. Fragmente von Hand zusammenzusetzen ist genau der Weg, auf dem die Reihenfolge und die Klammern verloren gingen
|-
| ''oWriter.ArrEnd'' nach ''RootArr'' || ''RootArr'' öffnet '''keine''' Ebene, es bestimmt nur die Klammer der Wurzel. Ein ''ArrEnd'' dazu ist ein Strukturfehler
|-
| Zahlen selbst formatieren (''NStr'', ''StrTran'') || <code>oWriter.Num('preis', nWert, 2)</code>. Selbst formatiert stand bei Werten ab 1000 der Tausendertrenner im JSON - gültiges JSON, falscher Wert, keine Meldung
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'|' + wert + '|'</code>) und mit ''Pos'' prüfen
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
|-
| <code>q.SaveData(…)</code> als Anweisung schreiben || ''SaveData'' liefert einen '''Boolean'''. Ein SQL-Fehler beim Schreiben wirft '''keine''' Exception und landet in '''keinem''' Protokoll - der Rückgabewert ist die einzige Meldung. Immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Je Feld ein eigener Setzer-Aufruf || Ein <code>qSqlInit</code>-Objekt, beliebig viele <code>qSet</code>, '''ein''' <code>SaveData</code>. Einzeln geschrieben kostet jedes Feld eine eigene Abfrage samt eigenem Write - und der Vorgang ist nicht mehr atomar, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Ein Wert je Zeile nachgeschlagen || In einer Liste sind das N Abfragen für eine Antwort. Über <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n) mitnehmen, siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]]
|-
| Ausgabeparameter vom Typ <code>var … : TDateTime</code> || Bringt die Skript-VM zum '''Absturz''' (Assertion in ''dwsStack.pas''), und zwar beim ersten '''Lesen''' des Werts - nicht schon beim Schreiben, die Ursache liegt also nicht dort, wo der Fehler auffällt. <code>var string</code>, <code>var Integer</code> und <code>var Double</code> laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und erst beim Aufrufer wandeln
|}

==Skript-Cache==

Der Server cached das kompilierte Skript pro Endpunkt (Schlüssel: ''sys_date'' des Endpunkts). Zusätzlich werden die Endpunkt-Definitionen pro Server-Profil in einem TTL-Cache (Standard 60 s) gehalten. Eine Skript-Änderung über F7 wird daher erst nach Ablauf dieses TTL (bzw. nach einer Cache-Invalidierung) wirksam - typischerweise innerhalb einer Minute, nicht zwingend sofort.

==Verfügbare Bibliotheken==

Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:

* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
* ''Base.qSqlReg'' - Schreibzugriffe
* ''lib_ScriptIO'' - Writer und Reader, siehe unten. '''System.JSON braucht ein Endpunkt-Skript nicht''' - der Writer erzeugt die Antwort, der Reader liest den Körper
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''
* ''lib_ScriptIO'' - ''TxRestWriter'', ''TxRestReader'' und die Zeitfunktionen ''RestIsoFromDate'' / ''RestDateFromIso'' / ''RestOffsetToMinutes''. Writer und Reader bekommt das Skript als Parameter; die Zeitfunktionen ruft es direkt

Die wichtigsten Aufrufe mit ihren Skript-Signaturen:

{| class="wikitable"
! Zweck !! Aufruf
|-
| Lesen || <code>DB_SOpen(oDB, cSql, q)</code>, dann <code>q.EoF</code>, <code>q.Next()</code>, <code>q.A2C('feld')</code> / <code>A2I</code> / <code>A2F</code> / <code>A2D</code> / <code>A2UID()</code>, am Ende <code>DB_Close(q)</code>
|-
| Neu anlegen || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('feld', wert)</code>, <code>if (not q.SaveData(NEW_RECORD)) then …</code>, <code>qSqlFree(q)</code> – der Rückgabewert ist Pflicht, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Ändern || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('sys_uid', cUid)</code>, <code>q.qSet(…)</code>, <code>if (not q.SaveData(UPDATE_RECORD)) then …</code>, <code>qSqlFree(q)</code> – '''nicht''' <code>qSqlRead</code>, siehe [[#Ändern: qSqlInit statt qSqlRead|Ändern]]. Alle Felder derselben Zeile in '''ein''' Objekt, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
|-
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
|}

{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
Skript nicht übersetzen.}}

Konkrete Beispiele:

* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

OBS/Kostenpflichtige Module/RESTServer/Endpunkte

2026-09-09T12:30:50Z

Rademacker:

{{Kostenpflichtige Module}}

= Endpunkte =

Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
realisiert und ist genau einem Server-Profil zugeordnet.

== Routing über Pfad-Templates ==

Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
'''Platzhalter''' enthalten:

* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
* '''Platzhalter''' in geschweiften Klammern – z. B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.

Beispiele für gültige Templates:

{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}

=== Präzedenz bei mehreren Treffern ===

Passen mehrere Templates auf denselben Pfad, '''gewinnt das spezifischste''' –
also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code>
das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf
<code>/orders/{uid}</code> matcht.

== Hauptfelder eines Endpunkts ==

{| class="wikitable"
! Feld !! Spalte !! Zweck
|-
| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code>
|-
| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
|-
| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
|-
| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
|-
| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
|-
| '''Info''' || – || Dokumentations-Freitext
|-
| '''Datei-Upload''' || <code>re_upload</code> || Erlaubt Datei-Uploads an diesem Endpunkt (<code>0</code> = aus, <code>1</code> = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
|-
| '''Max. Upload-Grösse''' || <code>re_upload_size</code> || Maximale Dateigrösse in MB. Leer/0 = Standard 25 MB. Überschreitung wird mit 413 abgelehnt.
|}

== Pfad-Parameter im Skript ==

Die aus den Platzhaltern erfassten Werte liest das Endpunkt-Skript über
<code>oReader.Path</code>:

<syntaxhighlight lang="pascal">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
cUid := oReader.Path('uid'); // aus /orders/{uid}
// ...
end;
</syntaxhighlight>

Diese Werte stammen aus dem Routing und können nicht durch den Client
überschrieben werden.

== Datei-Uploads ==

Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.

Die maximal zulässige Dateigrösse wird pro Endpunkt über <code>re_upload_size</code>
(in MB) festgelegt; ohne Angabe gilt der Standard von '''25 MB'''. Wird das
Limit überschritten, antwortet der Server mit '''413 Payload Too Large'''. Für
Uploads gilt nicht das JSON-Body-Limit (10 MB), sondern dieses Endpunkt-Limit.
Der Originalname (beim resumable Upload über den Header <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit 413/400 abgelehnt. Das Skript liest Pfad, Name, Content-Type und die SHA-256-Prüfsumme der gespeicherten Datei über <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code> und <code>UploadSha()</code>; bei <code>multipart/form-data</code> die übrigen Formularfelder über <code>oReader.Form('<name>')</code>.

'''Das Übertragungsprotokoll''' - Header, Statuscodes, Resume-Verhalten - steht auf einer eigenen Seite: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].

Unterstützt werden zwei Übertragungsarten:

* '''Einfacher Upload''' per <code>multipart/form-data</code> (eine Datei pro Request).
* '''Resumable/Chunked Upload''' per <code>Content-Range</code> (grosse Dateien, fortsetzbar nach Abbruch).

Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und
übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage,
DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und
Beispiele: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== HTTP-Methode ==

Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
Pfad-Formen (z. B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
'''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.

== URL-Struktur ==

<pre>
http://[Host][:Port][Pfad-Template]
</pre>

Beispiele:
* <code>https://api.meinserver.de/orders</code>
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>

== Versionierung ==

Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z. B. <code>/orders/v1</code> oder
<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:

# Bestehenden Endpunkt unverändert lassen.
# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
# Berechtigungen für neue Konsumenten setzen.
# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.

== Zugriffskontrolle ==

Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
dürfen.

{{Achtung|'''Ein Endpunkt besteht aus zwei Zeilen, und beide werden von Hand
gepflegt:''' der Eintrag in <code>RESTSRV_ENDPOINTS</code> und die Berechtigung
in <code>RESTSRV_ACCESS</code>. Fehlt die zweite, antwortet der Endpunkt
'''403''' - und sieht dabei fertig aus: Pfad, Skript und Server-Profil stehen
korrekt da, der Aufruf kommt trotzdem nicht durch. Das ist die häufigste Ursache
für ein „der Endpunkt ist doch angelegt" und kostet jedes Mal eine
Fehlersuche, weil der Statuscode nach einem Rechteproblem des Konsumenten
aussieht und nicht nach einer fehlenden Konfigurationszeile.

Beim Anlegen also '''immer beide Zeilen''', und beim Prüfen eines
<code>403</code> zuerst nachsehen, ob die zweite existiert.}} Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
Zugriff '''pro Pfad-Form''' granular vergeben (z. B. Lesen von
<code>/orders/{uid}</code> erlauben, aber das ändernde
<code>PUT /orders/{uid}/modules/{code}</code> nicht).

== Caching ==

Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
(TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher
erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
zwingend sofort.

== HTTP-Fehlercodes ==

{| class="wikitable"
! Code !! Ursache
|-
| '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
|-
| '''403''' || Zugang fehlt in der Berechtigungsliste
|-
| '''401''' || API-Key ungültig/fehlend, JWT abgelaufen oder Sitzung gesperrt (''AUTH_EXPIRED'')
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
|-
| '''405''' || Das Endpunkt-Skript hat für die angefragte HTTP-Methode keine Funktion; der Header <code>Allow</code> nennt die vorhandenen
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>)
|-
| '''429''' || Rate-Limit überschritten; die Antwort enthält den Header <code>Retry-After</code>
|-
| '''503''' || Eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet; die Antwort enthält <code>Retry-After</code>
|-
| '''409''' || Ein früherer Aufruf mit demselben <code>Idempotency-Key</code> ist ohne Ergebnis geblieben (<code>IDEMPOTENCY_UNRESOLVED</code>)
|-
| '''422''' || Derselbe <code>Idempotency-Key</code> wurde mit '''anderem''' Inhalt gesendet (<code>IDEMPOTENCY_KEY_REUSED</code>)
|-
| '''400''' || Die Anfrage wurde unverschlüsselt an einen TLS-Port geschickt (<code>http</code> statt <code>https</code>). Die Abweisung erfolgt vor Authentifizierung und Endpunkt-Skript
|}

Jede Fehlerantwort besteht aus einem <code>error</code>-Objekt mit
maschinenlesbarem Code - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. <code>201</code>, <code>204</code>, <code>409</code>, <code>422</code>) sowie Response-Header wie <code>ETag</code> oder <code>Location</code> - siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Idempotenz ==

Schickt ein Konsument bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code>
oder <code>DELETE</code> den Header <code>Idempotency-Key</code>, sorgt der Server
selbst dafür, dass eine wiederholte Sendung '''keine Zweitwirkung''' hat. Das gilt
für '''jeden''' Endpunkt - es muss weder am Endpunkt etwas eingestellt noch im
Skript etwas programmiert werden.

{| class="wikitable"
! Situation !! Antwort des Servers
|-
| Erster Aufruf || Endpunkt läuft normal, das Ergebnis wird zum Schlüssel gespeichert
|-
| Wiederholung, gleicher Inhalt || '''Gespeicherte Antwort''' (gleicher Statuscode, gleicher Body, gleiche Header) plus Header <code>Idempotent-Replay: true</code>. Das Skript läuft '''nicht'''
|-
| Wiederholung, anderer Inhalt || '''422''' <code>IDEMPOTENCY_KEY_REUSED</code> - derselbe Schlüssel für einen anderen Inhalt ist ein Client-Fehler
|-
| Erster Aufruf läuft noch || '''503''' <code>IDEMPOTENCY_IN_PROGRESS</code> mit <code>Retry-After</code>. Beim nächsten Versuch liegt die gespeicherte Antwort vor
|-
| Früherer Aufruf ohne Ergebnis || '''409''' <code>IDEMPOTENCY_UNRESOLVED</code>. Nur noch nach einem '''harten Abbruch''' des Dienstes zwischen Verarbeitung und Festschreiben; ob die Buchung stattgefunden hat, ist unbekannt. Der Aufräumlauf gibt solche Einträge nach 24 Stunden frei und protokolliert sie
|}

Wichtig für die Auslegung eines Endpunkts:

* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* Antwortet das Skript mit '''4xx''' (fachliche Ablehnung), wird der Schlüssel wieder '''freigegeben''' - der Konsument darf ihn nach Korrektur erneut verwenden. Sonst würde ein einziger Validierungsfehler den Schlüssel dauerhaft blockieren.
* Endet die Verarbeitung mit '''5xx''' oder einem Skript-Fehler, wird der Schlüssel '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden.
* Das ist eine bewusste Abwägung (geändert 2026-08-25): Bleibt der Schlüssel nach einem Serverfehler belegt, ist der Vorgang '''unwiederholbar''' - der Client bekommt dauerhaft 503 und müsste die erfasste Arbeit verwerfen. Garantierter Datenverlust wiegt schwerer als ein möglicher Doppelsatz.
* '''Folge für die Auslegung:''' ein schreibender Endpunkt sollte selbst wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.

Der Schlüssel gilt je '''Zugang, Methode und Pfad'''. Derselbe
<code>Idempotency-Key</code> an einem anderen Endpunkt ist damit ein eigener
Vorgang - der Konsument muss ihn nicht global eindeutig vergeben, aber pro Vorgang
'''stabil wiederverwenden''' (also nicht bei jedem Wiederholversuch neu erzeugen).

Die Einträge stehen in <code>RESTSRV_IDEMPOTENCY</code> und werden nach 30 Tagen
automatisch aufgeräumt. Einträge ohne Ergebnis werden '''nicht''' automatisch
gelöscht, sondern im Protokoll gemeldet.

== WebHooks ==

WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
gespeichert und der Endpunkt anschließend automatisch gelöscht.

Typischer Einsatz: OBS stösst einen Vorgang bei einem Fremdsystem an (Bezahldienst,
Versanddienstleister) und gibt diesem eine Rückruf-Adresse mit, die nur '''ein
einziges Mal''' gültig ist. Damit kann die Adresse nicht später erneut - oder von
jemand anderem - benutzt werden.

Ablauf:

# OBS legt einen Eintrag in <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, dessen Feld '''WebHook''' (<code>re_webhook</code>) auf diesen Eintrag zeigt. Ein Skript wird für diesen Endpunkt nicht gepflegt.
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
# Das Fremdsystem ruft die Adresse auf. Der Server legt den übergebenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code> ab, antwortet mit <code>{"status": "ok"}</code> und '''löscht den Endpunkt'''.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.

{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
normalen Endpunkt mit Skript anlegen.}}

OBS/Kostenpflichtige Module/RESTServer/Zugaenge

2026-09-09T12:30:38Z

Rademacker:

{{Kostenpflichtige Module}}

=Zugänge=

Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''

==Felder==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Name || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
| CORS-Origins || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt. '''Leer heisst nicht „keine Einschränkung", sondern „kein Browser-Zugriff"''' - siehe unten
|-
| mTLS-Subject || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
|-
| JWT || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
| JWT-Endpunkt || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
|-
| JWT-Key || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
| JWT-Exp || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
|}

==API-Key==

Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:

apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12

Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.

{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}

==Host-Beschränkung==

Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.

==CORS==

Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.

Format der Liste:

https://app.kunde.de;https://test.kunde.de;https://localhost:8080

Ablauf:

# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste '''aller''' Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste '''des aktuell verwendeten Zugangs''' geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.

Der Preflight kann nicht zugangsbezogen prüfen: der Browser schickt dabei keinen
''apikey'' mit, der Zugang ist zu diesem Zeitpunkt unbekannt. '''Die Durchsetzung
liegt deshalb auf Schritt 2''', nicht auf dem Preflight. Praktische Folge: trägt
'''ein''' Zugang auf dem Server ein ''*'' in seiner Liste, antwortet jeder
Preflight mit ''Access-Control-Allow-Origin: *'' - auch für Zugänge mit engerer
Liste. Deren eigentliche Anfrage wird trotzdem gegen die eigene Liste geprüft.

Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH'' (systemseitig festgelegt).

Bei den '''Anfrage-Headern''' spiegelt der Server im Preflight zurück, was der
Browser in ''Access-Control-Request-Headers'' angefragt hat. Damit sind eigene
Header eines Projekts - ''Idempotency-Key'', ''If-Match'', später
''Upload-Offset''/''Upload-Length'' - ohne Änderung am Server nutzbar. Fragt der
Preflight keine Header an, antwortet der Server mit der Liste
''Content-Type, apikey, Authorization, Accept''.

{{Hinweis|Die Header-Liste ist '''keine Schutzgrenze''' - das ist das Origin. Sie
sagt dem Browser nur, welche Header der Server versteht. Dazu kommt, dass die
Zugangsdaten dieser Schnittstelle in Headern stehen (''apikey'',
''Authorization'') und nicht in Cookies: es gibt also keine automatisch
mitgeschickte Berechtigung, die eine fremde Seite ausnutzen könnte.}}

===Was „leer" bedeutet===

{{Achtung|Ein '''leeres''' Feld CORS-Origins heisst '''nicht''' „keine
Einschränkung". Es heisst: '''jeder Aufruf mit ''Origin''-Header wird mit 403
abgelehnt'''. Für Clients '''ohne''' ''Origin''-Header - mobile Apps, Server,
curl - ändert das Feld gar nichts, sie werden nie gegen CORS geprüft.}}

Daraus ergeben sich drei sinnvolle Einstellungen:

{| class="wikitable"
! Feld !! Wirkung
|-
| leer || Kein Browser-Zugriff. Richtig für Zugänge, die nur von Apps oder Servern benutzt werden
|-
| konkrete Origins || Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen
|-
| ''*'' || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antwort aller anderen Zugänge - bewusst und sparsam verwenden
|}

Für eine Browser-Anwendung ist dieses Feld besonders wichtig, weil ihr API-Key
zwangsläufig im JavaScript liegt und damit öffentlich ist. Die Origin-Liste
verhindert dann, dass jemand den Key nimmt und von seiner eigenen Seite benutzt.
Sie ist allerdings kein Ersatz für eine Zugriffskontrolle: wer den Key hat,
umgeht CORS mit einem einzigen Aufruf ausserhalb des Browsers.

==JWT-Authentifizierung==

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).

'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.

Unterschieden wird nach Verb und Token-Art:

{| class="wikitable"
! Aufruf !! Ablauf
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
|}

{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}

===Phase 1: Token-Bezug===

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Body: {"username":"...", "password":"..."}

Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Prozedur ''Authenticate'' bereitstellen, die über den Writer schreibt:

* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_<name>'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)

Die Signatur lautet ''procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);'' - Details unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 28800,
"serverTime": "2026-06-29T15:30:12+02:00"}

Zum Aufbau der Antwort:

* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.

Beispiel mit Zusatzfeldern aus dem Skript:

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
"expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}

Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.

Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''' und reicht den Text aus dem Feld ''error'' als
''error.message'' an den Client durch - der Konsument kann ihn also direkt
anzeigen. Die Formulierung liegt damit beim Skript.

{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}

===Phase 2: Token-Verwendung===

Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:

GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi...

Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.

Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.

{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}

===Phase 3: Token erneuern (Refresh)===

Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Refresh-Token)

Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}

Verhalten bei einem bereits benutzten Refresh-Token:

{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
|}

Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

===Phase 4: Abmelden (Logout)===

Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
Access-Token im ''Authorization''-Header:

DELETE https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Access-Token)

HTTP/1.1 204 No Content

Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.

* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.

====Alle Geräte abmelden====

Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
''oWriter.JwtRevoke'', das jeder gewöhnliche Endpunkt aufrufen kann:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('all');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}

==Woher ein Anmelder seine Identität bekommt==

'''Diese Frage entscheidet das Skript des Zugangs, nicht der Server.''' Das
Authentifizierungs-Skript liegt je Zugang in <code>ra_jwt_script</code> - und
damit gilt für jede Anwendung ihre eigene Regel.

Das ist keine Kleinigkeit, sondern der Punkt, an dem sich zwei Anwendungen
unterscheiden. Ein Beispiel aus dem Betrieb: Ein Zugang für eine
Techniker-Anwendung lehnt jeden Benutzer ohne Mitarbeiterzuordnung
(<code>BENUTZ.b_mitarbeiter</code>) ab - '''bewusst''', denn ein Techniker ohne
Zuordnung bekäme eine leere Auftragsliste und würde den Fehler bei sich suchen.
Für einen Kundenzugang wäre genau dieselbe Regel falsch: sie träfe '''jeden'''
Anmelder.

Wer einen zweiten Zugang für eine andere Anwendung anlegt, prüft deshalb als
Erstes: Woraus besteht die Identität dieser Anmelder, und welche Ablehnung ist
für sie richtig? Ein kopiertes Skript bringt die Regel der anderen Anwendung
mit, und sie fällt erst auf, wenn sich der erste echte Anmelder nicht anmelden
kann.

==Sitzungen (RESTSRV_TOKEN)==

Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt".

* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.

==mTLS-Subject-Prüfung==

Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.

Beispiele für Subject-Strings im Cert (OneLine-DN):

/C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
/C=DE/O=Kunde GmbH/CN=client-test.kunde.de

Mit '''CN=client-prod.kunde.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Kunde GmbH;CN=client-prod.kunde.de''.

==Listen-Funktionen==

In der Zugänge-Liste (allein):

* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang

Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):

* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-09-09T12:30:27Z

Rademacker:

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

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

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# 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 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.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|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 [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|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/[Pfad-Template]

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.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen bleiben absichtlich stehen und werden ab 24 Stunden im Protokoll gemeldet - sie sind ein Support-Fall, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==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''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* 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.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf gibt den Eintrag nach 24 Stunden von selbst frei; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer

2026-09-09T12:30:07Z

Rademacker:

{{Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

Der REST-Server ist die '''universelle Schnittstelle''' Ihrer OBS-Installation nach außen. Er macht aus Ihrem OBS einen Dienst, mit dem andere Programme - Webseiten, Apps, Geräte, Kundensysteme, Cloud-Dienste - direkt sprechen können. Statt Daten manuell zu exportieren, zu mailen oder über Umwege bereitzustellen, holen sich angebundene Systeme genau die Information, die sie brauchen, in dem Moment, in dem sie sie brauchen - oder liefern neue Daten direkt in OBS ab.

Für Anwender, die nicht selbst programmieren, bedeutet das: '''Was bisher nur manuell, per Datei-Import oder über Spezialschnittstellen ging, lässt sich jetzt automatisieren.''' Eine Webseite zeigt live aktuelle Lagerbestände. Mitarbeiter erfassen Zeiten über das Handy, ohne dass jemand Excel-Listen einpflegen muss. Ein Kunde stößt per Bestelltaste in seinem System einen Vorgang in Ihrem OBS an. Ein Lieferant meldet Wareneingänge automatisch zurück. Jeder dieser Anwendungsfälle wird einmal eingerichtet und läuft danach automatisch.

Technisch gesehen ist der REST-Server ein in OBS integrierter, voll konfigurierbarer '''HTTP/HTTPS-Dienst''', dessen Endpunkte über in OBS gepflegte Pascal-Skripte realisiert werden. Jeder Endpunkt bekommt eine eigene Adresse, eine eigene Logik und eine eigene Berechtigungsstruktur. Rückgaben erfolgen ausschliesslich im JSON-Format. Damit lassen sich beliebige Lese- und Schreibvorgänge auf der OBS-Datenbank realisieren, ohne dass externe Systeme direkten Datenbank-Zugriff erhalten - das ganze OBS-Regelwerk (Rechte, Validierung, Geschäftslogik) bleibt aktiv.

Im Ergebnis ist der REST-Server kein einzelnes Feature, sondern ein '''Werkzeugkasten''': Was an Daten oder Funktionen in OBS verfügbar ist, kann über den REST-Server auch nach außen angeboten - oder von außen entgegengenommen - werden. Die Bandbreite reicht vom einfachen Lese-Endpunkt für ein Webseiten-Widget bis hin zu kompletten B2B-Integrationen mit Mandanten- und Rollen-Trennung.

Aufruf des Moduls in OBS:
'''Stammdaten''' -> '''Z Weitere Stammdaten''' -> '''REST-Server'''

==Anwendungsbereiche==

Die folgenden Einsatzfälle sind typische Beispiele, an denen sich der praktische Nutzen ablesen lässt. Es ist keine abschliessende Liste - alles, was sich in OBS-Skripten abbilden lässt, kann auch über einen Endpunkt bereitgestellt werden.

{{Hinweis|Dies sind Beispiele. Für die konkrete Entwicklung können, je nach Komplexität, weitere Kosten anfallen.}}

===Webseiten und Kundenportale===

* '''Live-Daten auf der eigenen Webseite:''' Lagerbestände, Verfügbarkeiten, Preise, Auftragsstatus aus OBS direkt anzeigen, ohne tägliche Datei-Exports.
* '''Kundenportale:''' Kunden sehen ihre offenen Posten, Auftragshistorie, Lieferscheine. Die Seite holt sich die Daten zur Anzeigezeit direkt aus OBS, jeder Kunde sieht nur seine eigenen Daten.
* '''Trackingseiten:''' Status einer Bestellung, eines Auftrags oder einer Reparatur für Endkunden, abrufbar über eine Sendungsnummer.

===Mobile Anwendungen und Außendienst===

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''QR-/Barcode-Scanner und Lagergeräte:''' Wareneingang, Inventur, Kommissionierung direkt in OBS abbilden, ohne zwischengeschaltete Software.
* '''Außendienst-Apps:''' Techniker sehen ihre Aufträge, dokumentieren Einsätze, erfassen Material - synchronisiert mit OBS.

===Anbindung von Drittsystemen===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''Buchhaltungs- und ERP-Systeme:''' Bidirektionaler Austausch von Belegen, Stammdaten und Buchungen.
* '''CRM- und Marketing-Tools:''' Personendaten, Aktivitäten oder Mailing-Empfänger werden synchron gehalten.
* '''Logistikdienstleister:''' Versandaufträge werden übergeben, Tracking-Informationen zurückgeliefert.

===Automatisierte Rückmeldungen (WebHooks)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''Versanddienste:''' Statusmeldungen (verschickt, zugestellt, retour) werden direkt im passenden Vorgang dokumentiert.
* '''Cloud-Workflows:''' Externe Automatisierungs-Plattformen (Make, Zapier, n8n, ...) stoßen OBS-Vorgänge an oder werden von OBS aus angesprochen.

===Geschäftspartner-Kommunikation (B2B)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''Kunden-Schnittstelle:''' Grosskunden bestellen direkt aus ihrem ERP heraus, Stammdaten und Konditionen werden zentral gepflegt.
* '''Sichere Maschine-zu-Maschine-Kommunikation:''' Mit Mutual-TLS (mTLS) wird sichergestellt, dass nur die freigeschalteten Partnersysteme - und niemand sonst - mit OBS sprechen können.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''Verbindung mehrerer Standorte:''' Verteilte Systeme tauschen Daten über definierte Endpunkte aus, ohne offene Datenbankverbindungen.
* '''Datenbereitstellung für Dashboards und Auswertungen:''' BI-Tools (Power BI, Grafana, ...) lesen aufbereitete Kennzahlen direkt aus OBS.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''Fehler werden weniger.''' Jede manuelle Stelle ist eine mögliche Fehlerquelle; jede Automatisierung eine Stelle, an der nichts mehr schiefgehen kann.
* '''Neue Geschäftsmodelle werden möglich.''' Kunden- und Lieferantenportale, Self-Service-Funktionen, App-Anbindungen lassen sich aufbauen, ohne ein zweites System pflegen zu müssen.
* '''Bestehende Software bleibt verbunden.''' Statt eine vorhandene Anwendung ablösen zu müssen, kann sie über den REST-Server an OBS angedockt werden - in beiden Richtungen.
* '''Skaliert mit:''' Was klein anfängt (ein einzelner Endpunkt für eine Webseite) kann zu einer kompletten Integrations-Plattform ausgebaut werden, ohne dass die Grundlage gewechselt werden muss.

==Architektur im Überblick==

Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:

{| class="wikitable"
! Baustein !! Tabelle !! Zweck
|-
| Server || RESTSRV_SERVER || TLS-Profil + eigene HTTP-Server-Instanz, kann mehrfach existieren
|-
| Bindung || RESTSRV_BINDINGS || IP-Adresse + Port pro Server
|-
| Zugang || RESTSRV_ACCOUNT || API-Key, optionale Host- und CORS-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| Protokoll || RESTSRV_PROTO || Laufende Ereignisse, Fehler, Audit-Einträge
|-
| Statistik || RESTSRV_STATS || Aufrufzähler, Antwortzeiten und HTTP-Status pro Endpunkt
|}

Eine Anfrage durchläuft folgende Stationen:

# Rate-Limit-Prüfung (pro API-Key bzw. IP und global, Schwellen je Server-Profil)
# Authentifizierung über den API-Key (Header ''apikey'')
# CORS-Prüfung (sofern ''Origin''-Header gesetzt)
# Optional: JWT-Prüfung - Signatur, Ablauf und Sitzung (sofern für den Zugang aktiviert)
# Routing: Auflösung des Pfads über die Pfad-Templates der Endpunkte
# Prüfung der Berechtigung (Zugang -> Endpunkt)
# Idempotenz-Prüfung (nur bei POST/PUT/PATCH/DELETE '''mit''' ''Idempotency-Key''-Header)
# Ausführung des Endpunkt-Skripts (oder WebHook-Antwort)
# Festschreiben des Ergebnisses im Idempotenz-Speicher (sofern in Schritt 7 reserviert)
# JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag

==Adressierung==

Ein Endpunkt wird über ein '''Pfad-Template''' angesprochen, das den Pfad nach dem Host beschreibt und Platzhalter enthalten kann:

http://[Hostadresse][:Port][Pfad-Template]

Beispiele:

https://api.meinserver.de/kalender/v1
https://api.meinserver.de/orders/{uid}
https://api.meinserver.de/orders/{uid}/modules/{code}

Statische Segmente müssen exakt passen; Platzhalter in geschweiften Klammern (z.B. {uid}) matchen einen beliebigen Wert und stehen im Skript als Pfad-Parameter zur Verfügung. Eine Versionskennung wird als statisches Segment ins Template aufgenommen (z.B. /kalender/v1), um eine Funktionalität zu verändern, ohne bestehende Konsumenten zu brechen. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==Unterstützte HTTP-Methoden==

Der Server akzeptiert die Methoden '''GET''', '''POST''', '''PUT''', '''DELETE''' und '''PATCH''' sowie '''OPTIONS''' (CORS-Preflight, ohne Skript-Aufruf). Jede Methode wird im Endpunkt-Skript als gleichnamige Funktion implementiert. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Datei-Uploads==

Endpunkte, die dafür freigeschaltet sind (<code>re_upload</code>), nehmen Dateien
per <code>multipart/form-data</code> oder als fortsetzbaren '''Resumable-Upload'''
(<code>Content-Range</code>) entgegen. Die maximale Grösse wird pro Endpunkt
festgelegt (<code>re_upload_size</code>, Standard 25 MB); Überschreitung
ergibt 413, ein Upload an einen nicht freigeschalteten Endpunkt 415. Der Server
legt die Datei temporär ab und übergibt dem Skript den Pfad; die weitere
Verarbeitung (z.B. DMS-Ablage) übernimmt das Skript. Details:
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Doppelte Sendungen abfangen (Idempotenz)==

Ein Client, der nach einem Timeout dieselbe Anfrage erneut schickt, darf keine
Zweitbuchung auslösen. Der Server erledigt das selbst: Sendet ein Aufruf mit
'''POST''', '''PUT''', '''PATCH''' oder '''DELETE''' den Header
<code>Idempotency-Key</code>, merkt sich der Server Schlüssel und Ergebnis in
'''RESTSRV_IDEMPOTENCY'''. Eine Wiederholung mit demselben Schlüssel und demselben
Inhalt bekommt die '''gespeicherte Antwort''' zurück - das Endpunkt-Skript läuft
gar nicht erst an.

* '''Ohne den Header ändert sich nichts.''' Bestehende Endpunkte verhalten sich unverändert.
* '''Kein Schalter am Endpunkt.''' Die Mechanik greift automatisch, sobald der Header anliegt.
* '''Das Skript muss nichts tun.''' Eine eigene Idempotenz-Logik im Skript ist nicht mehr nötig.

Details und die Statuscodes: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Sitzungen und Abmelden==

Ein JWT trägt seine Gültigkeit in sich: der Server prüft Signatur und Ablauf und
braucht dafür keine Datenbank. Genau deshalb liesse sich ein ausgegebener Token
von sich aus auch nicht mehr zurückziehen - ein verlorenes Gerät wäre bis zum
Ablauf des Tokens weiter nutzbar.

Der Server führt deshalb zu jedem ausgestellten Token-Paar eine Zeile in
'''RESTSRV_TOKEN''' und prüft jeden Zugriff dagegen. Daraus ergeben sich drei
Eigenschaften:

* '''Abmelden wirkt sofort.''' Ein ''DELETE'' auf den JWT-Endpunkt sperrt die Sitzung; alle Token dieser Sitzung sind damit unmittelbar ungültig, auch die noch nicht abgelaufenen. Anmelden, Erneuern und Abmelden laufen also über einen einzigen Endpunkt, und für das Abmelden ist kein Skript nötig.
* '''Ein Refresh-Token gilt genau einmal.''' Beim Erneuern wird es entwertet. Wird es später erneut vorgelegt, gilt das als Diebstahl oder Fehlfunktion: die betroffene Sitzung wird komplett gesperrt und der Vorfall protokolliert.
* '''Alle Geräte abmelden.''' Ein gewöhnlicher Endpunkt kann über das Antwortfeld ''_OBS_JWT_REVOKE'' auch alle Sitzungen eines Benutzers sperren - der Support-Fall „Gerät verloren".

{{Achtung|Mit der Einführung dieser Prüfung verlieren '''alle vorher
ausgestellten Token''' ihre Gültigkeit, weil sie zu keiner Sitzung gehören.
Angemeldete Konsumenten müssen sich nach dem Update einmalig neu anmelden.}}

Der Speicher pflegt sich selbst: Zeilen werden gelöscht, sobald sowohl das
Access- als auch das Refresh-Token abgelaufen sind. Details und die Skript-Seite:
[[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Fehlerformat==

Jede Fehlerantwort des Servers hat dieselbe Form: ein einziges ''error''-Objekt
mit maschinenlesbarem Code, Support-Kennung, Meldung und Korrelations-ID:

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00E2RTPDY",
"message": "Ungültiges oder abgelaufenes Token",
"traceId": "20260817T091233123-00001A"
}
}
</pre>

* '''code''' - sprechender Bezeichner (z.B. ''AUTH_EXPIRED'', ''NOT_FOUND'', ''RATE_LIMITED'', ''INTERNAL_ERROR''), an dem ein Client seine Reaktion festmachen kann, ohne Texte auszuwerten.
* '''uid''' - OBS-Kennung der Codestelle. Für die Support-Recherche gedacht, nicht zur Auswertung im Client.
* '''message''' - Text für den Client. Interne Fehlerdetails stehen nie darin, sondern ausschliesslich im Protokoll '''RESTSRV_PROTO'''.
* '''traceId''' - Korrelations-ID. Steht zusätzlich im Header ''X-Trace-Id'' und in jeder zugehörigen Logzeile.

Ein Endpunkt-Skript kann eigene Codes setzen; siehe
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

{{Achtung|''Fehlercode'', ''Nachricht'' und ''traceId'' stehen '''nur''' im
''error''-Objekt, nicht flach daneben - der Wert von
''Fehlercode'' heisst jetzt ''error.uid'', ''Nachricht'' entspricht
''error.message''. Clients, die die flachen Felder auswerten, müssen angepasst
werden.}}

==Sicherheitsmerkmale==

Der REST-Server enthält eine Reihe von Schutzmechanismen:

* '''Rate-Limit:''' Standardmässig max. 10 fehlgeschlagene und 120 erfolgreiche Anfragen pro API-Key (Account) bzw. IP und 60 Sekunden, max. 600 Anfragen global pro 60 Sekunden. Beim Überschreiten wird HTTP 429 mit ''Retry-After''-Header zurückgegeben. Die vier Schwellen lassen sich '''pro Server-Profil''' hinterlegen; die Zähler laufen ebenfalls getrennt je Profil, ein überlastetes Profil bremst das andere also nicht mit aus. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].
* '''Body-Limit:''' max. 10 MB Request-Body (JSON), max. 1024 Zeichen pro Header- oder Query-Parameter. Datei-Uploads laufen über einen separaten Pfad und sind pro Endpunkt auf <code>re_upload_size</code> MB begrenzt (Standard 25 MB).
* '''Sensible Felder''' (''password'', ''token'', ''secret'', ''apikey'', ''authorization'', ''cookie'', ...) werden in Protokoll-Ausgaben automatisch maskiert.
* '''Widerrufbare Token:''' Jedes ausgestellte Token-Paar gehört zu einer Sitzung in '''RESTSRV_TOKEN''' und wird bei '''jedem''' Zugriff dagegen geprüft. Eine Abmeldung wirkt damit sofort und nicht erst mit dem Ablauf des Tokens; ein Refresh-Token gilt genau einmal. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].
* '''Reserviertes Präfix:''' Parameter-Namen mit Präfix ''_OBS_'' können von aussen nicht gesetzt werden, sie sind für den Server reserviert (z.B. JWT-Claims).
* '''Geblockte Header:''' ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key'' werden nicht an das Skript durchgereicht.
* '''TLS:''' Bei Profilen mit aktivem TLS fährt der Server ohne Zertifikat und Key nicht hoch. Plain-HTTP ist nur für ein dediziertes Debug-Profil möglich.
* '''mTLS''' (Mutual TLS): erzwingt, dass jeder Client ein gültiges Client-Zertifikat vorlegt. Optional kann pro Zugang ein erwarteter Subject-DN hinterlegt werden.
* '''DNS-Cache:''' Host-zu-IP-Auflösungen für die Zugangs-Host-Prüfung werden 5 Minuten gecached.

==Protokoll==

Die Tabelle '''RESTSRV_PROTO''' enthält alle relevanten Ereignisse: erfolgreiche und abgelehnte Anfragen, TLS-/JWT-Fehler, Bindungs-Ereignisse, Skript-Fehler. Einträge sind nach Datum, Uhrzeit und Host (IP oder Account-Name) sortiert. Das Protokoll ist die erste Anlaufstelle bei Störungen. Jede Antwort trägt zudem eine Korrelations-ID (Response-Header ''X-Trace-Id''), die in den Protokoll-Einträgen wiederzufinden ist.

==Statistik==

Die Tabelle '''RESTSRV_STATS''' enthält eine Statistik aller bearbeiteten Anfragen mit Zugang, Endpunkt, Methode, HTTP-Status und Laufzeit in Millisekunden. Aufruf der Statistik:

* Aus der Endpunkt-Liste: F8 zeigt die Statistik des markierten Endpunkts.
* Aus der Zugänge-Liste: F8 zeigt die Statistik des markierten Zugangs.

==Konsole==

Wird der REST-Server nicht als Dienst, sondern interaktiv gestartet, erscheint eine farbige Konsole mit Live-Log. Die wichtigsten Befehle:

{| class="wikitable"
! Befehl !! Wirkung
|-
| ''show <n>'' || Zeigt die Details zum Debug-Eintrag ''#n'' (z.B. Request-Header, Response-Body), JSON wird farbig formatiert
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Einträge landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]] - API-Keys, JWT, CORS, Host-Beschränkung
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

OBS/Kostenpflichtige Module/RESTServer/Beispiel6

2026-09-01T09:12:01Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 6: Datei-Upload und Ablage=

Dieses Beispiel zeigt einen Endpunkt, der '''Dateien entgegennimmt''': Ein
Aussendienst-Mitarbeiter fotografiert vor Ort ein Gerät, die App lädt das Foto zum
Auftrag hoch, der Server legt es ab und verknüpft es mit dem Vorgang.

Der Ablauf ist derselbe für Belege aus einem Scanner, Unterschriften-Bilder oder
Prüfprotokolle als PDF. Behandelt werden beide Übertragungsarten - der einfache
Upload für kleine Dateien und der fortsetzbare Upload für grosse.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App'', API-Key zufällig generiert, JWT aktiv
* '''Endpunkt:''' ''/orders/{uid}/photos'', Profil ''Public-API''
** '''Datei-Upload''' auf '''Ja''' setzen (<code>re_upload = 1</code>)
** '''Max. Upload-Grösse''' auf ''20'' (MB) setzen
* '''Berechtigung:''' Zugang ''Mobile-App'' für den Endpunkt freischalten

{{Hinweis|Ohne den Haken '''Datei-Upload''' lehnt der Server jeden Upload mit
'''415''' ab und das Skript läuft gar nicht erst an. Das ist die häufigste Ursache,
wenn ein Upload "ohne erkennbaren Grund" scheitert.}}

==Was der Server erledigt, bevor das Skript läuft==

Der Server nimmt die Datei entgegen, prüft die Grösse, legt sie in einem temporären
Verzeichnis ab und übergibt dem Skript drei Parameter:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_UPLOAD_PATH || Vollständiger Pfad zur temporären Datei
|-
| _OBS_UPLOAD_NAME || Originaldateiname, wie ihn der Client gesendet hat
|-
| _OBS_UPLOAD_CONTENTTYPE || Content-Type der Datei
|-
| _OBS_UPLOAD_SHA256 || SHA-256 der gespeicherten Datei (hex, klein)
|}

Zwei Dinge sind beim Schreiben des Skripts wichtig:

* '''<code>oBody</code> ist bei Uploads immer <code>nil</code>.''' Der Request-Body ist die Datei, kein JSON. Zusatzangaben (Kategorie, Bemerkung) kommen deshalb als '''Query-Parameter''' mit - oder, bei <code>multipart/form-data</code>, als weitere '''Formularfelder'''; die stehen dem Skript als <code>_OBS_FORM_<name></code> zur Verfügung.
* '''Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt.''' Der Server räumt sie nicht selbst weg.

==Endpunkt-Skript ''/orders/{uid}/photos''==

Das Skript prüft den Dateityp, baut einen Zielpfad aus Auftrag und Zeitstempel,
verschiebt die Datei dorthin und schreibt einen Verweis in die Datenbank.

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
const ZIEL_BASIS = 'D:\OBS\Daten\Auftragsfotos\';
var oRes, oErr, oHdr: TJSONObject;
cUid : string;
cTmpPfad : string;
cOrigName: string;
cTyp : string;
cEndung : string;
cKategorie: string;
cZielDir : string;
cZielName: string;
cZielPfad: string;
qNeu : TqSQL;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];
cTmpPfad := oParams.Values['_OBS_UPLOAD_PATH'];
cOrigName := oParams.Values['_OBS_UPLOAD_NAME'];
cTyp := oParams.Values['_OBS_UPLOAD_CONTENTTYPE'];
cKategorie := oParams.Values['kategorie']; // Query-Parameter, nicht Body

// 1) Gehoert der Auftrag zum Mandanten aus dem Token?
if (not AuftragGehoertZuMandant(oParams.Values['_OBS_JWT_CLAIM_tenant'], cUid)) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'NOT_FOUND');
oErr.AddPair('message', 'Auftrag nicht gefunden');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 404);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 2) Dateityp gegen eine Whitelist pruefen - niemals gegen eine
// Blacklist, und niemals dem Content-Type allein vertrauen.
cEndung := Lower(ExtractFileExt(cOrigName));
if ((cEndung <> '.jpg') and (cEndung <> '.jpeg') and (cEndung <> '.png') and (cEndung <> '.pdf')) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'Nur JPG, PNG und PDF sind zulässig');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 3) Zielname selbst bilden. Den Originalnamen NICHT als Pfad
// verwenden - er kommt vom Client und kann '..\' enthalten.
cZielDir := ZIEL_BASIS + DToS(Date()) + '\' + cUid + '\';
cZielName := DToSF(Now()) + '_' + GlobalUID() + cEndung;
cZielPfad := cZielDir + cZielName;

MyForceDirectories(cZielDir);

if (not FMove(cTmpPfad, cZielPfad)) then begin
// Fehlgeschlagenes Verschieben ist ein Serverproblem -> 500.
// Der Idempotency-Key wird bei 5xx wieder freigegeben, der
// Client darf denselben Schluessel erneut senden.
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'INTERNAL_ERROR');
oErr.AddPair('message', 'Datei konnte nicht abgelegt werden');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 500);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 4) Verweis in der Datenbank ablegen
qNeu := qSqlInit(oDB, 'AUFTRAG_DOKUMENT');
qNeu.qSet('ad_auftrag' , cUid);
qNeu.qSet('ad_pfad' , cZielPfad);
qNeu.qSet('ad_dateiname', cOrigName);
qNeu.qSet('ad_typ' , cTyp);
qNeu.qSet('ad_kategorie', cKategorie);
qNeu.qSet('ad_datum' , Now());
// Rueckgabewert auswerten: ohne das bestaetigt der Endpunkt eine
// Ablage, die es nicht gibt - die Datei liegt dann im Zielverzeichnis,
// aber ohne Verweis in der Datenbank.
if (not qNeu.SaveData(NEW_RECORD)) then begin
qSqlFree(qNeu);
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'INTERNAL_ERROR');
oErr.AddPair('message', 'Verweis konnte nicht gespeichert werden');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 500);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;
qSqlFree(qNeu);

// 5) 201 mit Location auf die abgelegte Datei
oHdr := TJSONObject.Create();
oHdr.AddPair('Location', '/orders/' + cUid + '/photos/' + cZielName);

oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('dateiname', cZielName);
oRes.AddPair('groesse' , FSize(cZielPfad));
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|Soll die Datei statt in ein Verzeichnis in das '''OBS-Dokumenten-System'''
wandern, ersetzt der DMS-Aufruf die Schritte 3 bis 5. Welche Funktion dafür
zuständig ist, hängt vom eingesetzten Dokumenttyp ab - bitte mit dem OBS-Support
klären.}}

==Test mit curl==

Einfacher Upload einer Datei (''-F'' erzeugt ''multipart/form-data''):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-F "datei=@C:\Fotos\geraet.jpg" ^
"https://api.meinserver.de/orders/4711/photos?kategorie=VORHER"

Antwort:

HTTP/1.1 201 Created
Location: /orders/4711/photos/20260817091233_A1B2C3.jpg
X-Trace-Id: 20260817T091233123-00001A

{"dateiname":"20260817091233_A1B2C3.jpg","groesse":248113}

Ein Upload an einen Endpunkt '''ohne''' Upload-Freigabe:

HTTP/1.1 415 Unsupported Media Type

Eine Datei über der eingestellten Grenze:

HTTP/1.1 413 Payload Too Large

==Grosse Dateien: fortsetzbarer Upload==

Bei einem Foto aus dem Mobilfunknetz reisst die Verbindung schnell einmal ab. Für
solche Fälle überträgt der Client die Datei in Teilstücken und kann nach einem
Abbruch dort weitermachen, wo er aufgehört hat. '''Am Endpunkt-Skript ändert sich
dafür nichts''' - der Server sammelt die Teilstücke selbst ein und ruft das Skript
erst auf, wenn die Datei vollständig ist.

Der erste Teil trägt den Dateinamen (Base64-kodiert im Header
<code>Upload-Metadata</code>) und liefert eine <code>Upload-Id</code> zurück:

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Content-Range: bytes 0-1048575/5000000" ^
-H "Upload-Metadata: filename Z2VyYWV0LmpwZw==,filetype aW1hZ2UvanBlZw==" ^
--data-binary "@teil1.bin" ^
https://api.meinserver.de/orders/4711/photos

HTTP/1.1 308 Resume Incomplete
Upload-Id: 7f2a9c84...
Upload-Offset: 1048576
Range: bytes=0-1048575

Jeder weitere Teil sendet die ''Upload-Id'' mit. Der letzte Teil bekommt die
normale Antwort des Skripts (hier '''201'''). Nach einem Abbruch fragt der Client
den Stand ab und setzt dort auf:

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Content-Range: bytes */5000000" -H "Upload-Id: 7f2a9c84..." ^
https://api.meinserver.de/orders/4711/photos

HTTP/1.1 308 Resume Incomplete
Upload-Offset: 3145728

{{Hinweis|Der Zwischenstand liegt im Arbeitsspeicher des Dienstes. Wird der
REST-Dienst neu gestartet, muss ein unvollständiger Upload von vorn beginnen.}}

==Doppelte Uploads vermeiden==

Bricht die Verbindung ab, nachdem der Server die Datei schon abgelegt hat, würde ein
Wiederholversuch dasselbe Foto ein zweites Mal einliefern. Dagegen sendet der Client
den Header <code>Idempotency-Key</code> - für jedes Foto einen eigenen, über alle
Wiederholversuche hinweg denselben:

-H "Idempotency-Key: foto-4711-0003"

Der Server erkennt die Wiederholung und liefert die '''gespeicherte 201-Antwort'''
samt Header <code>Idempotent-Replay: true</code> zurück, ohne das Skript erneut zu
starten. Es entsteht also weder eine zweite Datei noch ein zweiter DB-Eintrag.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz.

==Was zeigt das Beispiel?==

* Endpunkt mit '''Datei-Upload-Freigabe''' (<code>re_upload</code>) und eigener Grössenbegrenzung.
* Zugriff auf die hochgeladene Datei über ''_OBS_UPLOAD_PATH'', ''_OBS_UPLOAD_NAME'' und ''_OBS_UPLOAD_CONTENTTYPE''.
* Zusatzangaben als '''Query-Parameter''', weil ''oBody'' bei Uploads ''nil'' ist.
* '''Whitelist''' für zulässige Dateitypen und ein '''selbst gebildeter Zielname''' - der Originalname landet nie im Pfad.
* Übernahme der temporären Datei mit ''FMove''; ohne diesen Schritt bleibt sie liegen.
* Antwort mit '''201''' und ''Location''-Header.
* Fortsetzbarer Upload ohne jede Änderung am Skript.
* Schutz gegen doppelte Einlieferung über den ''Idempotency-Key''.

==Siehe auch==

* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Upload-Parameter und Protokoll im Detail
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Freigabe, Grössenlimit, Idempotenz
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5]] - Schreibzugriff mit Statuscodes und ETag

OBS/Kostenpflichtige Module/RESTServer/Beispiel3

2026-09-01T09:11:48Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 3: Datensatz anlegen mit JSON-Body=

Dieses Beispiel zeigt einen Endpunkt mit allen vier CRUD-Methoden (GET, POST, PUT, DELETE). Es geht um Tickets eines externen Servicedesks, der Tickets ueber den OBS REST-Server in OBS einliefern, abrufen, aktualisieren und schliessen kann.

{{Hinweis|Dieses Beispiel adressiert ein einzelnes Ticket über einen Query-Parameter (''?id...''). Alternativ lässt sich dieselbe Ressource über ein Pfad-Template wie ''/tickets/{id}'' ansprechen; die ID steht dann als ''oParams.Values['_OBS_PATH_id']'' bereit. Ein vollständiges Beispiel dazu zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].}}

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'', Bindung 0.0.0.0:443
* '''Zugang:''' ''Servicedesk-X''
** API-Key: zufaellig generiert
** Host: ''servicedesk.kunde.de'' (DNS-gebunden, IP-Zugriff wird abgelehnt)
** JWT: nicht aktiv
* '''Endpunkt:''' ''tickets/v1'', Profil ''Public-API''
* '''Berechtigung:''' Zugang ''Servicedesk-X'' fuer Endpunkt ''tickets/v1'' freigeschaltet

==Endpunkt-Skript ''tickets/v1''==

<syntaxhighlight lang="pascal" line>
//------------------------------------------------------------------------------
// Hilfsfunktion: einzelnes Ticket als JSON-Objekt aufbauen
//------------------------------------------------------------------------------

function _TicketAsJSON(qTicket: TxFQuery): TJSONObject;
begin
result := TJSONObject.Create();
result.AddPair('id' , qTicket.A2UID());
result.AddPair('nr' , qTicket.A2C('ti_nr'));
result.AddPair('betreff' , qTicket.A2C('ti_betreff'));
result.AddPair('status' , qTicket.A2C('ti_status'));
result.AddPair('beschr' , qTicket.A2C('ti_beschr'));
result.AddPair('aenderung' , DTToSQL(qTicket.A2D('ti_aend_dat')));
end;

//------------------------------------------------------------------------------
// Hilfsfunktion: ein Feld aus dem JSON-Body als String lesen.
// Generics gibt es im Skript nicht - oBody.TryGetValue<string>(...) laesst sich
// nicht uebersetzen. GetValue liefert nil, wenn das Feld fehlt.
//------------------------------------------------------------------------------

function _BodyStr(oBody: TJSONObject; const cFeld: string): string;
var oVal: TJSONValue;
begin
result := '';
if (oBody = nil) then begin
exit;
end;
oVal := oBody.GetValue(cFeld);
if (Assigned(oVal)) then begin
result := oVal.Value;
end;
end;

//------------------------------------------------------------------------------
// Hilfsfunktion: Fehlerantwort im einheitlichen Format aufbauen.
// Fachliche Ablehnungen als 4xx melden, nicht als 200 mit Fehlertext.
//------------------------------------------------------------------------------

function _Fehler(oParams: TStrings; nStatus: integer; const cCode, cMsg: string): string;
var oRes: TJSONObject;
oErr: TJSONObject;
begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , cCode);
oErr.AddPair('message', cMsg);
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes := TJSONObject.Create();
try
oRes.AddPair('_OBS_HTTP_STATUS', nStatus);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------
// GET /tickets/v1?id=... - einzelnes Ticket
// GET /tickets/v1 - alle offenen Tickets
//------------------------------------------------------------------------------

function Get(oParams: TStrings; oBody: TJSONObject): string;
var cSql : string;
qData : TxFQuery;
oArr : TJSONArray;
cId : string;
begin
cId := oParams.Values['id'];

if (not Empty(cId)) then begin
cSql := 'SELECT * FROM tickets WHERE sys_uid = ' + DB_SQLVal(cId);
if (DB_SOpen(oDB, cSql, qData)) then begin
result := _TicketAsJSON(qData).ToJSON();
end else begin
result := _Fehler(oParams, 404, 'NOT_FOUND', 'Ticket nicht gefunden');
end;
DB_Close(qData);
end else begin
oArr := TJSONArray.Create();
try
cSql := 'SELECT * FROM tickets WHERE ti_status <> "9" ORDER BY ti_aend_dat DESC';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oArr.Add(_TicketAsJSON(qData));
qData.Next();
end;
end;
DB_Close(qData);

result := oArr.ToJSON();
finally
MyFreeAndNil(oArr);
end;
end;
end;

//------------------------------------------------------------------------------
// POST /tickets/v1 - neues Ticket anlegen
// Body: { "betreff":"...", "beschr":"..." }
//------------------------------------------------------------------------------

function Post(oParams: TStrings; oBody: TJSONObject): string;
var xTicket : TqSQL;
cId : string;
cBetreff: string;
cBeschr : string;
lOk : Boolean;
oRes : TJSONObject;
begin
if (not Assigned(oBody)) then begin
result := _Fehler(oParams, 400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;

cBetreff := _BodyStr(oBody, 'betreff');
cBeschr := _BodyStr(oBody, 'beschr');

if (Empty(cBetreff)) then begin
result := _Fehler(oParams, 422, 'VALIDATION_FAILED', 'Feld "betreff" fehlt');
exit;
end;

cId := GetNewId(oDB);

xTicket := qSqlInit(oDB, 'tickets');
xTicket.lNoSysUID := True;
try
xTicket.qSet('sys_uid' , cId);
xTicket.qSet('ti_nr' , DB_NeuNum(oDB, 'tickets', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
xTicket.qSet('ti_betreff' , cBetreff);
xTicket.qSet('ti_beschr' , cBeschr);
xTicket.qSet('ti_status' , '1');
xTicket.qSet('ti_anl_dat' , Now());
xTicket.qSet('ti_aend_dat', Now());
// SaveData liefert einen Boolean. Ein SQL-Fehler - etwa Duplicate entry
// auf einem eindeutigen Index - wirft KEINE Exception und steht in
// keinem Protokoll. Ohne diese Auswertung antwortet der Endpunkt mit
// 201, ohne etwas angelegt zu haben.
lOk := xTicket.SaveData(NEW_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
result := _Fehler(oParams, 500, 'INTERNAL_ERROR', 'Ticket konnte nicht angelegt werden');
exit;
end;

oRes := TJSONObject.Create();
try
oRes.AddPair('id' , cId);
oRes.AddPair('status', 'created');
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------
// PUT /tickets/v1 - Ticket aktualisieren
// Body: { "id":"...", "status":"...", "beschr":"..." }
//------------------------------------------------------------------------------

function Put(oParams: TStrings; oBody: TJSONObject): string;
var xTicket: TqSQL;
lOk : Boolean;
cId : string;
cStat : string;
cBeschr: string;
begin
if (not Assigned(oBody)) then begin
result := _Fehler(oParams, 400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;

cId := _BodyStr(oBody, 'id');
cStat := _BodyStr(oBody, 'status');
cBeschr := _BodyStr(oBody, 'beschr');

if (Empty(cId)) then begin
result := _Fehler(oParams, 422, 'VALIDATION_FAILED', 'Feld "id" fehlt');
exit;
end;

if (not DB_LSeek(oDB, 'tickets', 'sys_uid = ' + DB_SQLVal(cId))) then begin
result := _Fehler(oParams, 404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;

// Zum Aendern qSqlInit mit sys_uid, nicht qSqlRead: qSqlRead liest den
// Altsatz und schreibt nur Aenderungen - ein unveraenderter Wert erzeugt
// gar kein Write und SaveData liefert False.
xTicket := qSqlInit(oDB, 'tickets');
xTicket.qSet('sys_uid', cId);
try
if (not Empty(cStat)) then xTicket.qSet('ti_status' , cStat);
if (not Empty(cBeschr)) then xTicket.qSet('ti_beschr' , cBeschr);
xTicket.qSet('ti_aend_dat', Now());
lOk := xTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
result := _Fehler(oParams, 500, 'INTERNAL_ERROR', 'Ticket konnte nicht geaendert werden');
exit;
end;

result := '{"status":"updated"}';
end;

//------------------------------------------------------------------------------
// DELETE /tickets/v1?id=... - Ticket schliessen (Soft-Delete via Status=9)
//------------------------------------------------------------------------------

function Delete(oParams: TStrings; oBody: TJSONObject): string;
var xTicket: TqSQL;
cId : string;
lOk : Boolean;
begin
cId := oParams.Values['id'];
if (Empty(cId)) then begin
result := _Fehler(oParams, 422, 'VALIDATION_FAILED', 'Parameter "id" fehlt');
exit;
end;

if (not DB_LSeek(oDB, 'tickets', 'sys_uid = ' + DB_SQLVal(cId))) then begin
result := _Fehler(oParams, 404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;

xTicket := qSqlInit(oDB, 'tickets');
xTicket.qSet('sys_uid', cId);
try
xTicket.qSet('ti_status' , '9');
xTicket.qSet('ti_aend_dat', Now());
lOk := xTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
result := _Fehler(oParams, 500, 'INTERNAL_ERROR', 'Ticket konnte nicht geschlossen werden');
exit;
end;

result := '{"status":"closed"}';
end;
</syntaxhighlight>

==Aufruf mit curl==

Liste aller offenen Tickets:

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

Einzelnes Ticket:

curl -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"

Neues Ticket anlegen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"betreff\":\"Drucker offline\",\"beschr\":\"Etage 2, Raum 23\"}" ^
https://api.meinserver.de/tickets/v1

Ticket aktualisieren:

curl -X PUT -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"id\":\"abc-123\",\"status\":\"2\"}" ^
https://api.meinserver.de/tickets/v1

Ticket schliessen:

curl -X DELETE -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"

==Aufruf aus PHP==

<syntaxhighlight lang="php" line>
<?php
$apikey = '[API-KEY]';
$base = 'https://api.meinserver.de/tickets/v1';

function rest($method, $url, $apikey, $body = null) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL , $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
$headers = ['apikey: ' . $apikey];
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res, true);
}

// Neues Ticket anlegen
$neu = rest('POST', $base, $apikey, [
'betreff' => 'Drucker offline',
'beschr' => 'Etage 2, Raum 23'
]);
$id = $neu['id'];

// Status aktualisieren
rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2']);

// Liste auslesen
$alle = rest('GET', $base, $apikey);
foreach ($alle as $t) {
echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
}
?>
</syntaxhighlight>

==Was zeigt das Beispiel?==

* Saubere Trennung der CRUD-Methoden in einem Endpunkt.
* Verwendung des JSON-Body fuer komplexere Eingangsdaten (POST, PUT).
* Verwendung von Query-Parametern fuer einfache Werte (GET, DELETE).
* Soft-Delete ueber Status-Aenderung statt physischer Loeschung.
* Eindeutige Audit-UIDs (''Y00CXXXXxx'') fuer jeden DB-Zugriff zur Nachvollziehbarkeit.
* Host-gebundener Zugang als zweite Sicherheitsebene neben dem API-Key.
* Alternativ: ID per Pfad-Parameter statt Query-Parameter (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4]]).

OBS/Kostenpflichtige Module/RESTServer/Beispiel4

2026-09-01T09:11:35Z

Rademacker:

{{Kostenpflichtige Module}}
= Beispiel 4 – Pfad-Parameter (REST-Routing über Templates) =

Dieses Beispiel zeigt das '''Pfad-Template-Routing''' mit Platzhaltern. Eine
Auftrags-Ressource wird über drei Endpunkte abgebildet:

{| class="wikitable"
! Methode + Pfad !! Zweck
|-
| <code>GET /orders</code> || Liste aller offenen Aufträge
|-
| <code>GET /orders/{uid}</code> || Einzelner Auftrag per UID
|-
| <code>PUT /orders/{uid}/modules/{code}</code> || Status eines Auftrags-Moduls ändern
|}

Die Platzhalter <code>{uid}</code> und <code>{code}</code> stehen im Skript als
<code>oParams.Values['_OBS_PATH_uid']</code> bzw.
<code>oParams.Values['_OBS_PATH_code']</code> zur Verfügung.

== Einrichtung in OBS ==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' auf <code>0.0.0.0:443</code>.
* '''Zugang:''' ''Orders-Client'' mit API-Key, Zugriff auf die drei Endpunkte.
* '''Endpunkte''' (je ein Eintrag in <code>RESTSRV_ENDPOINTS</code>, alle Profil ''Public-API''):

{| class="wikitable"
! Endpunkt !! Pfad-Template !! Skript-Methode
|-
| <code>orders</code> || <code>/orders</code> || <code>Get</code> (Liste)
|-
| <code>orders</code> || <code>/orders/{uid}</code> || <code>Get</code> (Einzel)
|-
| <code>orders</code> || <code>/orders/{uid}/modules/{code}</code> || <code>Put</code>
|}

== Endpunkt-Skript 1: <code>GET /orders</code> (Liste) ==

<syntaxhighlight lang="pascal">
// Hilfsfunktion: ein Feld aus dem JSON-Body als String lesen.
// Generics gibt es im Skript nicht - oBody.TryGetValue<string>(...) laesst sich
// nicht uebersetzen. GetValue liefert nil, wenn das Feld fehlt.
function _BodyStr(oBody: TJSONObject; const cFeld: string): string;
var oVal: TJSONValue;
begin
result := '';
if (oBody = nil) then begin
exit;
end;
oVal := oBody.GetValue(cFeld);
if (Assigned(oVal)) then begin
result := oVal.Value;
end;
end;

// Hilfsfunktion: ein Auftrag als JSON-Objekt
function _OrderAsJSON(qOrder: TqSQL): TJSONObject;
begin
result := TJSONObject.Create();
result.AddPair('uid' , qOrder.A2UID());
result.AddPair('nr' , qOrder.A2C('au_nr'));
result.AddPair('kunde' , qOrder.A2C('au_kunde'));
result.AddPair('status' , qOrder.A2C('au_status'));
result.AddPair('aenderung', DTToSQL(qOrder.A2D('au_aend_dat')));
end;

function Get(oParams: TStrings; oBody: TJSONObject): string;
var cSql : string;
qData: TqSQL;
oArr : TJSONArray;
begin
oArr := TJSONArray.Create();

cSql := 'SELECT * FROM auftraege' +
' WHERE au_status <> ' + DB_SQLVal('9') +
' ORDER BY au_nr';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oArr.Add(_OrderAsJSON(qData));
qData.Next();
end;
end;

result := oArr.ToJSON();
end;
</syntaxhighlight>

== Endpunkt-Skript 2: <code>GET /orders/{uid}</code> (Einzel) ==

<syntaxhighlight lang="pascal">
//------------------------------------------------------------------------------
// Hilfsfunktion: Fehlerantwort im einheitlichen Format aufbauen.
// Fachliche Ablehnungen als 4xx melden, nicht als 200 mit Fehlertext.
//------------------------------------------------------------------------------

function _Fehler(oParams: TStrings; nStatus: integer; const cCode, cMsg: string): string;
var oRes: TJSONObject;
oErr: TJSONObject;
begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , cCode);
oErr.AddPair('message', cMsg);
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes := TJSONObject.Create();
try
oRes.AddPair('_OBS_HTTP_STATUS', nStatus);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

function _OrderAsJSON(qOrder: TqSQL): TJSONObject;
begin
result := TJSONObject.Create();
result.AddPair('uid' , qOrder.A2UID());
result.AddPair('nr' , qOrder.A2C('au_nr'));
result.AddPair('kunde' , qOrder.A2C('au_kunde'));
result.AddPair('status' , qOrder.A2C('au_status'));
result.AddPair('aenderung', DTToSQL(qOrder.A2D('au_aend_dat')));
end;

function Get(oParams: TStrings; oBody: TJSONObject): string;
var cUid : string;
cSql : string;
qData: TqSQL;
begin
// Pfad-Parameter aus /orders/{uid}
cUid := oParams.Values['_OBS_PATH_uid'];
if (cUid = '') then begin
result := _Fehler(oParams, 422, 'VALIDATION_FAILED', 'Pfad-Parameter "uid" fehlt');
exit;
end;

cSql := 'SELECT * FROM auftraege WHERE sys_uid = ' + DB_SQLVal(cUid);
if (DB_SOpen(oDB, cSql, qData)) and (not qData.EoF) then begin
result := _OrderAsJSON(qData).ToJSON();
end else begin
result := _Fehler(oParams, 404, 'NOT_FOUND', 'Auftrag nicht gefunden');
end;
end;
</syntaxhighlight>

== Endpunkt-Skript 3: <code>PUT /orders/{uid}/modules/{code}</code> ==

<syntaxhighlight lang="pascal">
//------------------------------------------------------------------------------
// Hilfsfunktion: Fehlerantwort im einheitlichen Format aufbauen.
// Fachliche Ablehnungen als 4xx melden, nicht als 200 mit Fehlertext.
//------------------------------------------------------------------------------

function _Fehler(oParams: TStrings; nStatus: integer; const cCode, cMsg: string): string;
var oRes: TJSONObject;
oErr: TJSONObject;
begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , cCode);
oErr.AddPair('message', cMsg);
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes := TJSONObject.Create();
try
oRes.AddPair('_OBS_HTTP_STATUS', nStatus);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

function Put(oParams: TStrings; oBody: TJSONObject): string;
var cUid : string;
cCode : string;
cStatus: string;
cSql : string;
qChk : TqSQL;
xMod : TqSQL;
cModUid: string;
lOk : Boolean;
begin
// Beide Pfad-Parameter
cUid := oParams.Values['_OBS_PATH_uid'];
cCode := oParams.Values['_OBS_PATH_code'];
if (cUid = '') or (cCode = '') then begin
result := _Fehler(oParams, 422, 'VALIDATION_FAILED', 'Pfad-Parameter "uid" oder "code" fehlt');
exit;
end;

// Nutzdaten kommen aus dem JSON-Body
cStatus := _BodyStr(oBody, 'status');
if (cStatus = '') then begin
result := _Fehler(oParams, 422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
exit;
end;

// Existenzpruefung - und zugleich der Schreib-Index. Ein SELECT auf die
// sys_uid liefert beides; ein 'SELECT *' waere hier verschenkte Arbeit.
cSql := 'SELECT sys_uid FROM auftrag_module' +
' WHERE am_auftrag = ' + DB_SQLVal(cUid) +
' AND am_code = ' + DB_SQLVal(cCode) + ' LIMIT 1';
cModUid := '';
if (DB_SOpen(oDB, cSql, qChk)) then begin
if (not qChk.EoF) then begin
cModUid := qChk.A2UID();
end;
end;
DB_Close(qChk);

if (cModUid = '') then begin
result := _Fehler(oParams, 404, 'NOT_FOUND', 'Modul nicht gefunden');
exit;
end;

// Update
// Der Satz wird ueber seine sys_uid geschrieben - qSqlRead waere hier
// ein zusaetzlicher Lesezugriff, und ein unveraenderter Wert wuerde gar
// kein Write erzeugen (SaveData liefert dann False).
xMod := qSqlInit(oDB, 'auftrag_module');
xMod.qSet('sys_uid' , cModUid);
xMod.qSet('am_status', cStatus);
// Rueckgabewert auswerten - ein Schreibfehler wirft keine Exception
lOk := xMod.SaveData(UPDATE_RECORD);
qSqlFree(xMod);

if (not lOk) then begin
result := '{"error":{"code":"INTERNAL_ERROR","message":"Status konnte nicht gespeichert werden"},"_OBS_HTTP_STATUS":500}';
exit;
end;

result := '{"status":"ok"}';
end;
</syntaxhighlight>

== Test mit curl ==

<syntaxhighlight lang="bash">
# Liste
curl -H "apikey: GEHEIM123" https://api.meinserver.de/orders

# Einzelner Auftrag (uid als Pfad-Parameter)
curl -H "apikey: GEHEIM123" https://api.meinserver.de/orders/4711

# Modul-Status aendern (uid + code als Pfad-Parameter, status im Body)
curl -X PUT \
-H "apikey: GEHEIM123" \
-H "Content-Type: application/json" \
-d '{"status":"21"}' \
https://api.meinserver.de/orders/4711/modules/A1
</syntaxhighlight>

== Was dieses Beispiel zeigt ==

* '''Eine Ressource, mehrere Pfad-Formen''' über getrennte Endpunkt-Einträge mit eigenem Skript und eigener Berechtigung.
* '''Pfad-Parameter''' werden über <code>{name}</code> im Template erfasst und im Skript als <code>oParams.Values['_OBS_PATH_name']</code> gelesen.
* Reihenfolge der Skript-Parameter: '''<code>oParams</code> zuerst, <code>oBody</code> danach''' (umgekehrt zur internen Dispatch-Reihenfolge).
* Präzedenz: ein statisches Segment (z. B. <code>/orders/summary</code>) hätte Vorrang vor <code>/orders/{uid}</code>.

== Siehe auch ==

* [[/OBS/Kostenpflichtige_Module/RESTServer/Endpunkte|Endpunkte]]
* [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]]

OBS/Kostenpflichtige Module/RESTServer/Beispiel5

2026-09-01T09:11:24Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz=

Dieses Beispiel zeigt einen schreibenden Endpunkt für eine mobile App: Aufträge werden mit echten HTTP-Statuscodes aktualisiert, konkurrierende Änderungen über ETag/If-Match abgesichert (Optimistic Concurrency) und doppelte Sendungen über einen Idempotency-Key abgefangen. Die Anmeldung nutzt JWT mit Custom-Claims (Mandant, Rollen) und einem Refresh-Token.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App''
** API-Key: zufällig generiert
** JWT aktiv, JWT-Endpunkt ''auth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
* '''Endpunkte''' (beide dem Profil ''Public-API'' zugeordnet):
** ''orders/{uid}'' - Auftrag lesen/Ändern
** ''orders/{uid}/material'' - Material erfassen
* '''Berechtigung:''' Zugang ''Mobile-App'' für beide Endpunkte freigeschaltet

{{Hinweis|Für das Abmelden gibt es '''keinen eigenen Endpunkt'''. Es läuft über
ein ''DELETE'' auf den JWT-Endpunkt ''auth'' und braucht daher weder eine Zeile
in ''RESTSRV_ENDPOINTS'' noch eine Berechtigung.}}

==JWT-Authentifizierungs-Skript (Zugang)==

Stellt Mandant und Rollen als Custom-Claims aus und löst über ''_OBS_JWT_REFRESH_ID'' ein Refresh-Token aus. Bei einem Refresh ruft der Server im selben Skript die Methode ''Refresh'' auf. Die Hilfsfunktionen (''PasswortPasst'', ''TechnikerMandant'', ''TechnikerRollen'') sind illustrativ und projektabhängig.

{{Hinweis|Eine '''eigene Sperrtabelle für Refresh-jti ist nicht nötig'''.
Einmalgebrauch, Rotation und Widerruf führt der Server in ''RESTSRV_TOKEN'' -
das Skript entscheidet nur, '''ob''' und '''mit welchen Rechten''' die Sitzung
fortgesetzt wird. Frühere Fassungen dieses Beispiels zeigten eine Skript-Tabelle;
wer sie übernommen hat, kann sie entfernen.}}

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser, cPass: string;
begin
oRes := TJSONObject.Create();
try
cUser := ''; cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username'); if (Assigned(oVal)) then cUser := oVal.Value;
oVal := oBody.GetValue('password'); if (Assigned(oVal)) then cPass := oVal.Value;
end;

if (PasswortPasst(cUser, cPass)) then begin
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser)); // z.B. "tech,lead"
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das Refresh-Token aus
// _OBS_JWT_REFRESH_EXP weggelassen -> Default 90 Tage
end else begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Login fehlgeschlagen');
end;
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------

function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cUser: string;
begin
oRes := TJSONObject.Create();
try
cUser := oParams.Values['_OBS_JWT_SUBJECT'];

// Das vorgelegte Refresh-Token hat der Server bereits geprueft und
// entwertet. Hier wird nur entschieden, ob die Sitzung fortgesetzt
// werden darf - und mit welchen Rechten.
if (not TechnikerAktiv(cUser)) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
result := oRes.ToJSON();
exit;
end;

// Mandant und Rollen NEU lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID());
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}'' - ändern mit ETag / If-Match==

''GET'' liefert den Auftrag samt ''ETag'' (Version), ''PUT'' prüft Rolle und ''If-Match''.

<syntaxhighlight lang="pascal" line>
function Get(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
cUid: string;
nVer: integer;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];
if (not AuftragLesen(oParams.Values['_OBS_JWT_CLAIM_tenant'], cUid, oRes, nVer)) then begin
oRes.AddPair('_OBS_HTTP_STATUS', 404);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'NOT_FOUND'));
result := oRes.ToJSON();
exit;
end;
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nVer));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------

function Put(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
cUid: string;
nAktuell, nIfMatch: integer;
begin
oRes := TJSONObject.Create();
try
// nur Rolle "lead" darf ändern - Rolle kommt aus dem Token, nicht aus dem Body.
// Mit Trennzeichen suchen: ein blosses Pos('lead', ...) wuerde auch in
// "leadless" oder "teamlead" treffen.
if (Pos(',lead,', ',' + oParams.Values['_OBS_JWT_CLAIM_roles'] + ',') = 0) then begin
oRes.AddPair('_OBS_HTTP_STATUS', 403);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'FORBIDDEN_ROLE'));
result := oRes.ToJSON();
exit;
end;

cUid := oParams.Values['_OBS_PATH_uid'];
nAktuell := AuftragVersion(cUid);
nIfMatch := iVal(oParams.Values['if-match']);

if (nIfMatch <> nAktuell) then begin
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell));
oRes.AddPair('_OBS_HTTP_STATUS', 409);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'VERSION_CONFLICT'));
result := oRes.ToJSON();
exit;
end;

// AuftragSpeichern gibt den Rueckgabewert von SaveData durch. Ohne
// diese Pruefung antwortet der Endpunkt mit 200 und einem neuen ETag,
// obwohl nichts geschrieben wurde - siehe Scripting, Schreibfehler
// erkennen.
if (not AuftragSpeichern(cUid, oBody)) then begin // setzt Version auf nAktuell + 1
oRes.AddPair('_OBS_HTTP_STATUS', 500);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'INTERNAL_ERROR'));
result := oRes.ToJSON();
exit;
end;

oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell + 1));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}/material'' - idempotentes Anlegen==

''POST'' erfasst eine Materialposition: Validierungsfehler -> 422, erfolgreiches Anlegen -> 201.

Gegen doppelte Sendungen schickt der Client den Header ''Idempotency-Key''. '''Das
Skript muss dafür nichts tun''' - der Server erkennt den Header, merkt sich das
Ergebnis und liefert bei einer Wiederholung mit demselben Schlüssel die
gespeicherte Antwort zurück, ohne das Skript erneut zu starten (siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz). Das Skript kümmert sich nur um seine Fachlogik:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
oVal: TJSONValue;
cUid, cArtikel, cNeueUid: string;
nMenge: integer;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];

// 1) Validierung -> 422 mit traceId.
// Wichtig: fachliche Ablehnung als 4xx melden, nicht als 200 mit
// Fehlertext - nur dann gibt der Server den Idempotency-Key wieder
// frei und der Client darf ihn nach Korrektur erneut verwenden.
cArtikel := '';
nMenge := 0;
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('artikel'); if (Assigned(oVal)) then cArtikel := oVal.Value;
oVal := oBody.GetValue('menge'); if (Assigned(oVal)) then nMenge := iVal(oVal.Value);
end;
if ((Empty(cArtikel)) or (nMenge <= 0)) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'artikel und menge sind Pflicht');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 2) Buchen. Die Transaktionssteuerung bleibt beim Skript; der
// Idempotenz-Speicher des Servers läuft getrennt davon und
// umschliesst diesen Block nicht.
cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);

// MaterialAnlegen liefert Leerstring, wenn SaveData fehlgeschlagen
// ist. Diese Pruefung ist Pflicht: ein 201 auf einen gescheiterten
// Schreibvorgang ist der Fehler, den niemand findet - der Client
// haelt die Position fuer gebucht und wiederholt nicht einmal.
if (Empty(cNeueUid)) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'INTERNAL_ERROR');
oErr.AddPair('message', 'Die Position konnte nicht gebucht werden');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 500);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 3) Antwort vollständig aufbauen - genau sie wird eingefroren und bei
// einer Wiederholung erneut ausgeliefert.
oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('uid', cNeueUid);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Abmelden - ohne Endpunkt und ohne Skript==

Beim Abmelden soll das Gerät seine Sitzung wirklich verlieren, nicht erst mit dem
Ablauf des Tokens. Dafür ist '''nichts einzurichten''': ein ''DELETE'' auf den
JWT-Endpunkt mit dem Access-Token genügt, der Server sperrt die Sitzung in
''RESTSRV_TOKEN'' und antwortet 204.

Gesperrt wird die ganze Sitzung, also auch die Access-Token vorheriger
Erneuerungen. Ein zweiter Aufruf ist unschädlich und bleibt 204. Kann der Server
die Sitzung nicht sperren, antwortet er '''503''' mit ''Retry-After'' - die App
wiederholt den Abmeldevorgang dann.

Nur wenn beim Abmelden zusätzlich etwas passieren soll - hier: die
Geräteregistrierung für Push löschen -, braucht es einen eigenen Endpunkt. Er
erledigt seine Fachlogik und setzt ''_OBS_JWT_REVOKE'':

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cAlle: string;
begin
oRes := TJSONObject.Create();
try
PushRegistrierungLoeschen(oParams.Values['_OBS_JWT_CLAIM_technikerUid']);

// Optional: {"alleGeraete": true} meldet den Techniker ueberall ab.
// Diese Entscheidung gehoert bewusst in ein Skript - sie braucht eine
// Berechtigungspruefung, die der JWT-Endpunkt nicht leisten kann.
cAlle := 'session';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('alleGeraete');
if (Assigned(oVal)) and (Lower(oVal.Value) = 'true') then begin
cAlle := 'all';
end;
end;

oRes.AddPair('_OBS_JWT_REVOKE' , cAlle);
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"tech1\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/auth/

{"token":"eyJ...","accessToken":"eyJ...","refreshToken":"eyJ...",
"expiresIn":3600,"serverTime":"2026-06-29T15:30:12+02:00"}

Bei falschen Zugangsdaten antwortet der Server mit '''401''' und dem Text aus dem
Authenticate-Skript als ''error.message''.

Auftrag lesen (liefert den ETag-Header):

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711
... ETag: 7

ändern mit korrektem If-Match -> 200, mit veraltetem If-Match -> 409:

curl -i -X PUT -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "If-Match: 7" -H "Content-Type: application/json" ^
-d "{\"status\":\"erledigt\"}" ^
https://api.meinserver.de/orders/4711

Material idempotent erfassen (zweiter Aufruf mit gleichem Key -> gleiche Antwort, keine Doppelbuchung):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Idempotency-Key: 9c84-7f2a-..." -H "Content-Type: application/json" ^
-d "{\"artikel\":\"A100\",\"menge\":3}" ^
https://api.meinserver.de/orders/4711/material

Die Antwort des zweiten Aufrufs trägt zusätzlich den Header
''Idempotent-Replay: true'' - daran ist erkennbar, dass sie aus dem Speicher kam
und nichts erneut gebucht wurde.

Token erneuern (Refresh-Token im Authorization-Header an denselben JWT-Endpunkt):

curl -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer <refreshToken>" ^
https://api.meinserver.de/auth/

Die Antwort enthält ein neues Paar. Das alte Refresh-Token ist damit verbraucht:
ein zweiter Aufruf mit demselben Token antwortet '''401'''. Erfolgt er innerhalb
von 60 Sekunden, bleibt die Sitzung bestehen (paralleler Refresh der App); später
gilt er als Wiedervorlage und die '''ganze Sitzung wird gesperrt''' - der
Techniker muss sich neu anmelden, und der Vorfall steht mit IP im Protokoll.

Abmelden - DELETE auf denselben JWT-Endpunkt, Access-Token im Header:

curl -i -X DELETE -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/auth/

HTTP/1.1 204 No Content

Derselbe Token danach noch einmal verwendet:

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711

HTTP/1.1 401 Unauthorized

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00G9TOK09",
"message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden",
"traceId": "20260819T091233123-00001A"
}
}
</pre>

==Was zeigt das Beispiel?==

* Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422, 500.
* Jeder Schreibzugriff wird auf Erfolg geprüft - ein gescheitertes ''SaveData'' darf nicht als 200 oder 201 beim Client ankommen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting#Schreibfehler erkennen|Schreibfehler erkennen]]).
* Optimistic Concurrency über ''ETag'' (GET) und ''If-Match'' (PUT) -> 409 VERSION_CONFLICT.
* Idempotente Schreibzugriffe über den ''Idempotency-Key'' - '''vom Server erledigt''', das Skript enthält dafür keine Zeile Code.
* Rollenprüfung aus dem Token-Claim ''_OBS_JWT_CLAIM_roles'', nicht aus dem Body.
* JWT mit Custom-Claims (''tenant''/''roles'') und Refresh-Token mit Rotation - '''vom Server erledigt''', das Skript führt keine Sperrtabelle.
* Anmelden, Erneuern und Abmelden über '''einen''' Endpunkt - Abmelden als ''DELETE'', ohne eigene Endpunkt-Zeile und ohne Skript.
* ''_OBS_JWT_REVOKE'' für den Fall, dass beim Abmelden zusätzlich Fachlogik laufen soll oder alle Geräte gemeint sind.
* ''traceId'' im Fehler-Body für die Support-Nachverfolgung (auch als Header ''X-Trace-Id'').

OBS/Kostenpflichtige Module/RESTServer/Beispiel2

2026-09-01T09:11:05Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 2: Zeiterfassung als komplette Webanwendung=

Dieses Script dient zur Zeiterfassung über den REST-Server. Bei Seitenaufruf wird eine Liste von Kunden geladen und in einer Liste angezeigt.

Durch Rechtsklick auf einen Eintrag wird eine Liste an zugehörigen Tätigkeiten geladen, die nach Klick einen Timer starten.

Per Javascript werden Startzeit, Startdatum und andere Informationen wie Kunde und Personalnummer über die PHP-Scripte und das Endpunkt-Script in einer Datenbank gespeichert.

Der Status wird hierbei auf "1" gesetzt. Pausenzeiten werden nach Beenden einer Pause in der Datenbank gespeichert.

Durch Drücken des Stop-Buttons wird eine Lightbox mit einer Zusammenfassung aller zum Timer gehörenden Daten angezeigt. Hier hat man die Möglichkeit Tätigkeiten, abgelaufene Zeit und

Pausenzeit nachträglich zu bearbeiten. Durch Klick auf "Speichern" oder Druck auf F2 werden Endzeit und Enddatum gespeichert und der Status auf "21" gesetzt.

Nach Reload der Webseite wird anhand des Status in der Datenbank nach laufenden Timern gesucht und diese gegebenenfalls gestartet.

= Endpunkt-Script =
<syntaxhighlight lang="pascal">
procedure _AddJob(oArr: TJSONArray; id: String);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT CONCAT(za_text, ":",sys_uid) AS Job FROM zeiterfart ' +
'WHERE za_psnr = ' + DB_SQLVal(id) + ' AND za_inaktiv <> "1" ' +
'ORDER BY za_order';
if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oArr.Add(A_Query.A2C('Job'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddCustomer(oArr: TJSONArray);
var cSql : String;
A_Query : TxFQuery;
begin
cSql :=' SELECT * FROM' +
' (SELECT' +
' ps_nr,' +
' ps_such AS Kunde,' +
' perssta.sys_uid AS ps_sys_uid,' +
' "PE" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN perssta ON se_ref1 AND perssta.sys_uid = se_ref2' +
' WHERE se_nr = 0087' +
' AND ps_nr <> 100000' +
' UNION SELECT p_nr AS ps_nr,' +
' p_name1 AS ps_such,' +
' projekte.sys_uid AS ps_sys_uid,' +
' "PR" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN projekte ON se_ref1 = p_nr' +
' AND projekte.sys_uid = se_ref2 WHERE se_nr = 0087)' +
' A WHERE ps_nr IS NOT NULL' +
' ORDER BY Kunde ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oArr.Add(A_Query.A2C('Kunde'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddID(kunde: String; oArr: TJSONArray);
var cSql : String;
A_Query : TxFQuery;
begin
cSql :=' SELECT * FROM' +
' (SELECT' +
' ps_nr,' +
' ps_such AS Kunde,' +
' perssta.sys_uid AS ps_sys_uid,' +
' "PE" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN perssta ON se_ref1 AND perssta.sys_uid = se_ref2' +
' WHERE se_nr = 0087' +
' AND ps_nr <> 100000' +
' UNION SELECT p_nr AS ps_nr,' +
' p_name1 AS ps_such,' +
' projekte.sys_uid AS ps_sys_uid,' +
' "PR" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN projekte ON se_ref1 = p_nr' +
' AND projekte.sys_uid = se_ref2 WHERE se_nr = 0087)' +
' A WHERE ps_nr IS NOT NULL' +
' AND Kunde = ' + DB_SQLVal(kunde) +
' ORDER BY Kunde ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oArr.Add(A_Query.A2C('ps_nr'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddCHECK(oArr: TJSONArray);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT ze_starttime, zeiterfuser.sys_uid AS sysuid, zk_psnr, ' +
'za_text, ps_such, ze_startdate FROM ' +
'zeiterfuser LEFT JOIN zeiterfkomm ON ' +
'zk_messunguid = zeiterfuser.SYS_UID LEFT JOIN zeiterfart ' +
'ON zeiterfart.sys_uid = zeiterfuser.ze_uid AND ' +
'za_psnr = zeiterfkomm.zk_psnr LEFT JOIN perssta ON ' +
'ps_nr = zeiterfkomm.zk_psnr WHERE ze_status = 01 ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oArr.Add(A_Query.A2C('ze_starttime'));
oArr.Add(A_Query.A2C('zk_psnr'));
oArr.Add(A_Query.A2C('za_text'));
oArr.Add(A_Query.A2C('ps_such'));
oArr.Add(A_Query.A2C('sysuid'));
oArr.Add(A_Query.A2C('ze_startdate'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _getPauseTime(sysuid: String; oArr: TJSONArray);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT * FROM zeiterfuser WHERE sys_uid = ' + DB_SQLVal(sysuid);

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oArr.Add(A_Query.A2C('ze_pausezeit'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

//----------------Funktionen----------------------------------//

function POST(oParams: TStrings; oBody: TJSONObject): string;
var
oArr1 : TJSONArray;
cSql : String;

begin
if (oParams.values['choice']='job') then begin
oArr1 := TJSONArray.Create();
_AddJob(oArr1, oParams.values['id']);
result := oArr1.ToJSON();
end else if (oParams.values['choice']='customer') then begin
oArr1 := TJSONArray.Create();
_AddCustomer(oArr1);
result := oArr1.ToJSON();
end else if (oParams.values['choice']='id') then begin
oArr1 := TJSONArray.Create();
_AddID(oParams.values['selectedKunde'], oArr1);
result := oArr1.ToJSON();
end else if (oParams.values['choice']='check') then begin
oArr1 := TJSONArray.Create();
_AddCHECK(oArr1);
result := oArr1.ToJSON();
end else if (oParams.values['choice']='pauseTime') then begin
oArr1 := TJSONArray.Create();
_GetPauseTime(oParams.values['sysuid'], oArr1);
result := oArr1.ToJSON();
end;
end;

function PUT(oParams: TStrings; oBody: TJSONObject): string;
var
xZeit : TqSQL;
cUSER_SYSUID : String;
cKOMM_SYSUID : String;
lNew : Boolean;
cSql : String;
dDBNow : TDateTime;
begin
writeln('Choice: ' + oParams.values['choice']);
if (oParams.values['choice']='start') then
begin
dDBNow := DB_Now(oDB);
lNew := True;
if (empty(cUSER_SYSUID)) then begin
cUSER_SYSUID := GetNewId(oDB);
end;

xZeit := qSqlInit(oDB, 'zeiterfuser');
xZeit.lNoSysUID := True;

writeln('SYSUID: ' + oParams.values['jobID']);

xZeit.qSet('ze_user' , oParams.values['user']);
xZeit.qSet('ze_starttime' , oParams.values['uhrzeit']);
xZeit.qSet('ze_eigen' , '0101');
xZeit.qSet('ze_startdate' , oParams.values['datum']);
xZeit.qSet('ze_endtime' , oParams.values['endTime']);
xZeit.qSet('ze_enddate' , oParams.values['endDate']);
xZeit.qSet('ze_zeit' , '0');
xZeit.qSet('ze_pausezeit' , '0');
xZeit.qSet('ze_status' , oParams.values['status']);
xZeit.qSet('ze_berechnen' , 0);
xZeit.qSet('ze_officestar' , 0);
xZeit.qSet('ze_repa' , 0);
xZeit.qSet('ze_vorbereitung' , 0);
xZeit.qSet('ze_uid' , oParams.values['jobID']);
xZeit.qSet('sys_uid' , cUSER_SYSUID);

// SaveData meldet einen Fehler ueber den RUECKGABEWERT, nicht ueber eine
// Exception. Ohne diese Pruefung antwortet der Endpunkt mit Erfolg,
// obwohl nichts geschrieben wurde.
if (not xZeit.SaveData(lNew)) then begin
qSQLFree(xZeit);
result := 'ERROR: Zeiterfassung konnte nicht gespeichert werden';
exit;
end;
qSQLFree(xZeit);

//---------------------------------------------------------------------

xZeit := qSqlInit(oDB,'ZEITERFKOMM');
xZeit.lNoSysUID := True;

if (empty(cKOMM_SYSUID)) then begin
cKOMM_SYSUID := GetNewId(oDB);
end;

xZeit.qSet('zk_psnr' , oParams.values['psnr']);
xZeit.qSet('zk_starttime' , oParams.values['uhrzeit']);
xZeit.qSet('zk_startdate' , oParams.values['datum']);
xZeit.qSet('zk_kommentar' , oParams.values['comm']);
xZeit.qSet('zk_messunguid' , cUSER_SYSUID);
xZeit.qSet('sys_uid' , cKOMM_SYSUID);

if (not xZeit.SaveData(lNew)) then begin
qSQLFree(xZeit);
result := 'ERROR: Kommentar konnte nicht gespeichert werden';
exit;
end;
qSQLFree(xZeit);

result := cUser_SYSUID;

end else if (oParams.values['choice']='stop') then
begin

// Jeder Wert aus oParams geht durch DB_SQLVal - auch die, die wie
// Zahlen aussehen. Der Kommentar ist Freitext aus dem Browser, und
// ohne Quoting beendet ein Apostroph darin das SQL-Statement.
cSql := 'UPDATE zeiterfuser, zeiterfkomm ' +
' SET zeiterfuser.ze_zeit = ' + DB_SQLVal(oParams.values['elapsedTime']) +
', zeiterfuser.ze_endtime = ' + DB_SQLVal(oParams.values['vergZeit']) +
', zeiterfuser.ze_enddate = ' + DB_SQLVal(oParams.values['stopTimeValue']) +
', zeiterfuser.ze_pausezeit = ' + DB_SQLVal(oParams.values['elapsedPauseTime']) +
', zeiterfuser.ze_status = ' + DB_SQLVal(oParams.values['status']) +
', zeiterfkomm.zk_kommentar = ' + DB_SQLVal(oParams.values['comment']) +
' WHERE zeiterfuser.sys_uid = ' + DB_SQLVal(oParams.values['uid']) +
' AND zeiterfkomm.zk_messunguid = ' + DB_SQLVal(oParams.values['uid']);

if DB_SQLExec(oDB,cSql) then
begin
result := 'Die Daten wurden erfolgreich gespeichert!';
end else begin
result := 'Fehler!';
end;
end else if (oParams.values['choice']='pause') then
begin
writeln('Pausezeit: ' + oParams.values['pauseTime']);
cSql := 'UPDATE zeiterfuser SET ze_pausezeit ' +
'= ze_pausezeit + ' + DB_SQLVal(oParams.values['pauseTime']) +
' WHERE sys_uid = ' + DB_SQLVal(oParams.values['sysuid']);

if DB_SQLExec(oDB,cSql) then
begin
result := 'Die Daten wurden erfolgreich gespeichert!';
end else begin
result := 'Fehler!';
end;
end;
end;
</syntaxhighlight>

= HTML-Datei index.php =
<syntaxhighlight lang="html">
<!DOCTYPE html>
<html lang="de-DE">
<head>
<title>Ihr IT-Partner in Stade - Ernst Bergau GmbH</title>
<link rel="stylesheet" type="text/css" href="timestyle.css">
</head>
<script>
<?php
include('timer.js');
?>
</script>
<body>




<textarea id="search" type="text" rows="1" cols="50" oninput="searchCustomers(this.value)"></textarea>

<div class="kundenliste">
<ul id="kundenListe"></ul>
</div>
<table class="timer">
<tbody id="timerList"></tbody>
</table>
<table class="tabelleUeberschriften">
<thead>
<tr>
<th class="kunde">Kunde</th>
<th class="konto">Konto</th>
<th class="laufzeit">Laufzeit</th>
<th class="status">Status</th>
</tr>
</thead>
</table>

<div class="lightbox" id="lightbox">
<label class="commLabel" id="commLabel" for="comment">Kommentar</label>
<textarea class="comment" id="comment" rows="4" cols="50"></textarea>

<div class="bezZeitkonto">Zeitkonto</div>
<select class="dropButtonsLightbox" id="tätigkeit2Dropdown"></select>

<div class="bezDatum">Startdatum</div>
<input type="date" class="date" id="date">

<textarea disabled class="uhrzeit" id="uhrzeit"></textarea>

<div class="bezPerson">Person</div>
<textarea disabled class="eingPerson" id="eingPerson"></textarea>
<textarea disabled class="eingPersonZusatz" id="eingPersonZusatz"></textarea>

<div class="Std">Std</div>
<input type="number" class="outStd" id="outStd">
<div class="Min">Min</div>
<input type="number" class="outMin" id="outMin">
<div class="Sek">Sek</div>
<input type="number" class="outSek" id="outSek">

<div class="Pausenzeiten">Davon Pausenzeiten</div>
<div class="Std2">Std</div>
<input type="number" class="outStd2" id="outStd2">
<div class="Min2">Min</div>
<input type="number" class="outMin2" id="outMin2">
<div class="Sek2">Sek</div>
<input type="number" class="outSek2" id="outSek2">

<button class="saveButton" id="saveButton">Speichern</button>
<button class="closeButton" id="closeButton" onclick="closeLightboxOnSchliessen()">Schließen</button>
</div>

<div id="zweiteListe">
<ul id="taetigkeitListe"></ul>
</div>
</body>
</html>

</syntaxhighlight>

= Javascript-Datei timer.js =
<syntaxhighlight lang="javascript">
var api_key = 'Y00C75PODJ';
var url = 'http://127.0.0.1:8099/Zeiterfa/zeiterfa/v1';
var zaehler = -1;
var timerInterval;
var pauseTimerInterval;
var startTimeValue;
var selectedID = 0;
var elapsedTime;
var uid;
var idStop;
var time;
var selID = [];
var job = [];
var sys_uid = [];
var timers = [];
var pauseTimers = [];
var pauseTime = [];
var startdate = [];
var uhrzeit = [];
var datum = [];
var statusTimer = [];
var selectedJob = [];
var selectedKunde = [];
var tempSelectedKunde = [];
var parameter = [];

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------------Seitenaufruf---------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Bei Seitenaufruf werden die Funktionen----//
//----getCustomer und checkTimer aufgerufen und----//
//----die Kundenliste gefüllt und geprüft,----//
//----ob laufende timer vorhanden sind----//

window.onload = function() {

getCustomer();
checkTimer();
}

//-----------------------------------------------------------------------------------------------------------------------//
//-------------------------------------------------Daten auslesen--------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Eine Liste der Kunden wird ausgelesenund gespeichert----//

function getCustomer() {

var method = 'POST';
var choice = 'customer';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
populateListeKunde(responseData);
}
};
request.send(params);
}

//----Bei Rechtsklick auf Kunden wird----//
//----seine ID ausgelesen und gespeichert----//

function getCustomerID(selectedKunde, callback) {

var method = 'POST';
var choice = 'id';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&selectedKunde=" + encodeURIComponent(selectedKunde);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
selectedID = JSON.parse(request.responseText);
callback(selectedID);
}
};
request.send(params);
}

//----Anhand der Kunden-ID wird eine Liste von Tätigkeiten----//
//----für jeden Kunden ausgelesen und gespeichert----//

function getJob(id, callback) {

var method = 'POST';
var choice = 'job';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&id=" + encodeURIComponent(id);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
var Data = responseData.toString();
var teile = Data.split(",");
var jobid = [];

for (i=0; i<teile.length; i++) {
job[i] = teile[i].split(":")[0];
jobid[i] = teile[i].split(":")[1];
}
callback(job, jobid);
}
};
request.send(params);
}

//----Tätigkeitsliste wird nochmal zur Weiterverarbeitung gelesen----//

function getJobs(id) {

var method = 'POST';
var choice = 'job';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&id=" + encodeURIComponent(id);

var request = new XMLHttpRequest();

request.open("POST", "getData.php", false);
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
var data = responseData.toString();
var teile = data.split(",");
var jobid = [];

for (var i = 0; i < teile.length; i++) {
job[i] = teile[i].split(":")[0];
jobid[i] = teile[i].split(":")[1];
}
}
};
request.send(params);
}

//----Gespeicherte Pausezeit wird ausgelesen----//

function getPauseTime(sysuid, id) {

var method = 'POST';
var choice = 'pauseTime';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&sysuid=" + encodeURIComponent(sysuid);

var request = new XMLHttpRequest();

request.open("POST", "getData.php", false);
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
pauseTime[id].value = JSON.parse(request.responseText);

}
};
request.send(params);
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Listen--------------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Eine Liste wird mit Kundendaten gefüllt und angezeigt----//

function populateListeKunde(data) {

data.forEach(function(item) {
var listItem = document.createElement("li");
listItem.textContent = item;

listItem.addEventListener("contextmenu", function(event) {
event.preventDefault();

var selectedKunde = item;
getCustomerID(selectedKunde, function(selectedID) {
getJob(selectedID, function(job, jobid) {
showSecondList(job, jobid, item);
});
});
});

kundenListe.appendChild(listItem);
});
}

//----Eine zweite Liste wird mit Jobs gefüllt,----//
//----angezeigt und bei Klick auf einen Eintrag---//
//-------die Funktion startTimer aufgerufen-------//

function showSecondList(job, jobid, kundeItem) {

var zweiteListe = document.getElementById("zweiteListe");
zweiteListe.innerHTML = "";

job.forEach(function(item) {
var listItem = document.createElement("li");
listItem.textContent = item;

(function(capturedItem) {
listItem.addEventListener("click", function() {
startTimer(job, jobid, capturedItem, kundeItem);
});
}) (item);
zweiteListe.appendChild(listItem);
});

zweiteListe.style.display = "block";
document.addEventListener('keydown', closeSecondList);
document.addEventListener('click', closeSecondList);
}

//----Nach Klick auf Eintrag wird die Liste geschlossen----//
function closeSecondList() {

var zweiteListe = document.getElementById("zweiteListe");
zweiteListe.style.display = "none";
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Daten speichern-----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Startzeit, -datum, ID und Job werden gespeichert----//

function saveStartTime(user, uhrzeit, datum, endTime, endDate, status, psnr, Job, jobID) {

var method = 'PUT';
var choice = 'start';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&user=" + encodeURIComponent(user) +
"&uhrzeit=" + encodeURIComponent(uhrzeit) +
"&datum=" + encodeURIComponent(datum) +
"&endTime=" + encodeURIComponent(endTime) +
"&endDate=" + encodeURIComponent(endDate) +
"&status=" + encodeURIComponent(status)+
"&psnr=" + encodeURIComponent(psnr)+
"&Job=" + encodeURIComponent(Job)+
"&jobID=" + encodeURIComponent(jobID);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
sys_uid[zaehler].value = request.responseText;
}
};
request.send(params);
}

//----Pausezeit wird gespeichert----//

function savePauseTime(pauseTime, id) {

var method = 'PUT';
var choice = 'pause';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&pauseTime=" + encodeURIComponent(pauseTime) +
"&sysuid=" + encodeURIComponent(sys_uid[id].value);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {

if (this.readyState === 4 && this.status === 200) {
// alert(request.responseText);
}
};
request.send(params);
}

//----Stopzeit und -datum wird gespeichert----//

function saveStopTime(stopTimeValue, elapsedTime, elapsedPauseTime, status, uid, vergZeit, comment) {

var method = 'PUT';
var choice = 'stop';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&stopTimeValue=" + encodeURIComponent(stopTimeValue) +
"&elapsedTime=" + encodeURIComponent(elapsedTime) +
"&elapsedPauseTime=" + encodeURIComponent(elapsedPauseTime) +
"&status=" + encodeURIComponent(status) +
"&uid=" + encodeURIComponent(uid) +
"&vergZeit=" + encodeURIComponent(vergZeit)+
"&comment=" + encodeURIComponent(comment);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200 && timers.length === 0) {
location.reload();
}
};
request.send(params);
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Like-Suche----------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Durchsucht die Liste der Kunden auf alle einegegebenen Zeichen----//

function searchCustomers(text) {

text = text.toLowerCase();
var kundenListe = document.getElementById("kundenListe");
var listItems = kundenListe.getElementsByTagName("li");

for (i=0; i<listItems.length; i++) {
var item = listItems[i].textContent.toLowerCase();
if (item.includes(text)) {
listItems[i].style.display = "block";
}
else {
listItems[i].style.display = "none";
}
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------Vorhandenen Timer checken----------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Überprüft, ob es Einträge in Datenbank ohne----//
//----Endzeit gibt und startet entsprechend Timer----//

function checkTimer() {

var method = 'POST';
var choice = 'check';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200 && timers.length === 0) {
var responseData = JSON.parse(request.responseText);

if (responseData.length !== 0) {
startTimeValue = new Date();
var minutes = startTimeValue.getMinutes();
var seconds = startTimeValue.getSeconds();
var month = startTimeValue.getMonth() + 1;

responseData = responseData.toString();
var teile = responseData.split(",");

for (var i=0; i<teile.length; i+=6) {
uhrzeit.push({value: startTimeValue.getHours() + ":" + (minutes < 10 ? "0" + minutes : minutes) + ":" + (seconds < 10 ? "0" + seconds : seconds)});
datum.push({value: startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + startTimeValue.getDate()});

zaehler++;

statusTimer.push({value: 'Running'});
pauseTimers.push({value: 0});
pauseTime.push({value: 0});
timers.push({value: teile[i]});
}

var j=0;
for (var i=1; i<teile.length; i+=6) {
selID.push({value: teile[i]});
getJobs(selID[j].value);
j++;
}

fillArray(2, selectedJob, teile);
fillArray(3, selectedKunde, teile);
fillArray(4, sys_uid, teile);
fillArray(5, startdate, teile);

for (var i=0; i<timers.length; i++) {
var startZeitTeil = timers[i].value.split(":");
var startDatumTeil = startdate[i].value.split(".");

var diffMilli = new Date() - getStartdatum(startDatumTeil, startZeitTeil);
timers[i].value = Math.floor(diffMilli / 1000);
}

selecteID = 0;
startInterval(job);
}
}
};
request.send(params);
}

//----Arrays werden an diese Funktion übergeben und gefüllt----//

function fillArray(LZ, array, teile) {

var arrLZ = 0;
for (var i=LZ; i<teile.length; i+=6) {
array.push({value: teile[i]});
arrLZ++;
}
}

//----Startdatum wird errechnet----//
function getStartdatum(startDatumTeil, startZeitTeil) {

var startdatum = new Date(
parseInt(startDatumTeil[2]),
parseInt(startDatumTeil[1]) -1,
parseInt(startDatumTeil[0]),
parseInt(startZeitTeil[0]),
parseInt(startZeitTeil[1]),
parseInt(startZeitTeil[2])
);
return startdatum;
}

//-----------------------------------------------------------------------------------------------------------------------//
//-------------------------------------------------Interval--------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Interval für Timer wird gestartet----//

function startInterval(job, item, kundeItem, index) {

timerInterval = setInterval(function() {

for (i=0; i<timers.length; i++) {

timers[i].value += 1;
}
updateUI(job, item, kundeItem, index);
}, 1000);
}

//----Interval für Pausentimer wird gestartet----//

function pauseInterval(job, item, kundeItem, id) {

pauseTimerInterval = setInterval(function() {

for (i=0; i<pauseTimers.length; i++) {

pauseTimers[i].value += 1;
}
updateUI(job, item, kundeItem);
}, 1000);
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer starten----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----startTimer bereitet die nötigen Arrays vor,----//
//----speichert Startzeit und -datum,----//
//----beschreibt Arrays und Variablen entsprechend----//
//----und ruft die Funktion saveStartTime auf----//

function startTimer(jobs, jobid, selJob, kundeItem) {

var user = 999;
var endTime = "00:00:00";
var endDate = "0000-00-00";
var status = '01';
zaehler++;

startTimeValue = new Date();

var minutes = startTimeValue.getMinutes();
var seconds = startTimeValue.getSeconds();
uhrzeit.push({value: startTimeValue.getHours() + ":" + (minutes < 10 ? "0" + minutes : minutes) + ":" + (seconds < 10 ? "0" + seconds : seconds)});

var month = startTimeValue.getMonth() + 1;
datum.push({value: startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + startTimeValue.getDate()});

statusTimer.push({value: 'Running'});
pauseTimers.push({value: 0});
pauseTime.push({value: 0});
timers.push({value: 0});
selectedKunde.push({value: kundeItem});
selectedJob.push({value: selJob});
sys_uid.push({value: 0});

var index = jobs.indexOf(selJob);

saveStartTime(user, uhrzeit[zaehler].value, datum[zaehler].value, endTime, endDate, status, selectedID, selJob, jobid[index]);

clearInterval(timerInterval);
startInterval(jobs, selJob, kundeItem, index);

zweiteListe.style.display = "none";
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer stoppen----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Stopt den Timer, ändert den Status und ruft openLightbox auf----//

function stopTimer(job, item, kundeItem, index, id) {

idStop = id;
statusTimer[id].value = 'Stopped';
openLightbox(job, item, kundeItem, index, id);
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer pausieren--------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Pausiert den Timer und ändert den Status----//

function pauseTimer(job, item, kundeItem, id) {

pauseTimers[id].value = 0;
clearInterval(pauseTimerInterval);
pauseInterval(job, item, kundeItem, id);
}

//-----------------------------------------------------------------------------------------------------------------------//
//----------------------------------------------Button Pause-Start-------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Ruft die Funktion pauseTimer oder----//
//----savePauseTimer auf----//

function toggleButton(job, item, kundeItem, id) {

var button = document.getElementById(id);

if (button.innerHTML === "Pause") {

statusTimer[id].value = 'Paused';
pauseTimer(job, item, kundeItem, id);
}
else {

statusTimer[id].value = "Running";
savePauseTime(pauseTimers[id].value, id);
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Ausgabe des Timers-----------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Zeigt eine Liste mit einem oder mehreren----//
//----Timern und Buttons, verteilt dynamisch ID's----//
//----und ruft entsprechend der gedrückten----//
//----Buttons Funktionen auf----//

function updateUI(job, item, kundeItem, index) {
var timerList = document.getElementById("timerList");
timerList.innerHTML = '';

for (i=0; i<timers.length; i++) {
var neueReihe = document.createElement('tr')

//----Name des Kunden wird ausgegeben----//

var kundeEintrag = document.createElement('td');
kundeEintrag.style.position = "fixed";
kundeEintrag.style.top = (12 + i * 14) + "%";
kundeEintrag.style.width = "30%";
kundeEintrag.style.left = "0%";
kundeEintrag.style.textAlign = "center";
kundeEintrag.classList.add('kunde_k');
kundeEintrag.textContent = selectedKunde[i].value;
timerList.appendChild(kundeEintrag);

//----Gewählter Job wird ausgegeben----//

var kontoEintrag = document.createElement('td');
kontoEintrag.style.position = "fixed";
kontoEintrag.style.top = (12 + i * 14) + "%";
kontoEintrag.style.width = "30%";
kontoEintrag.style.left = "30%";
kontoEintrag.style.textAlign = "center";
kontoEintrag.classList.add('konto_k');
kontoEintrag.textContent = selectedJob[i].value;
timerList.appendChild(kontoEintrag);

//----Gestartete Timer werden in Liste----//
//----ausgegeben, pausierte Timer werden----//
//----Liste ausgegeben, sobald Timer gestoppt----//
//----wird Ausgabe in Lightbox----//

if (statusTimer[i].value === "Running") {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(timers[i].value);
timerList.appendChild(laufzeitElement);
}
else if (statusTimer[i].value === 'Paused') {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(pauseTimers[i].value);
timerList.appendChild(laufzeitElement);
}
else if (statusTimer[i].value === 'Stopped') {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(pauseTimers[i].value);
timerList.appendChild(laufzeitElement);

var zeit = formatElapsedTime(timers[i].value);
zeit = zeit.toString();
var teile = zeit.split(":");

var h = teile[0];
var m = teile[1];
var s = teile[2];

var outStdField = document.getElementById("outStd");
var outMinField = document.getElementById("outMin");
var outSekField = document.getElementById("outSek");

if (document.activeElement !== outStdField && document.activeElement !== outMinField && document.activeElement !== outSekField) {
document.getElementById("outStd").value = h;
document.getElementById("outMin").value = m;
document.getElementById("outSek").value = s;
}

var hEnd = document.getElementById("outStd").value;
var mEnd = document.getElementById("outMin").value;
var sEnd = document.getElementById("outSek").value;
time = hEnd + ":" + mEnd + ":" + sEnd;
}

//----Status (Running, Paused, Stopped) wird ausgegeben----//

var statusTimerElement = document.createElement('td');
statusTimerElement.style.position = "fixed";
statusTimerElement.style.top = (12 + i * 14) + "%";
statusTimerElement.style.width = "15%";
statusTimerElement.style.left = "75%";
statusTimerElement.style.textAlign = "center";
statusTimerElement.classList.add('status_s');
statusTimerElement.textContent = statusTimer[i].value;
timerList.appendChild(statusTimerElement);

//----Pause Button mit dynamisch vergebener ID wird ausgegeben----//

if (statusTimer[i].value === "Running") {
var pauseButton = document.createElement('button')
pauseButton.id = i;
pauseButton.classList.add('pauseButton');
pauseButton.style.position = "fixed";
pauseButton.style.top = (12 + i * 14) + "%";
pauseButton.style.left = "90%";
pauseButton.style.height = "9.4%";
pauseButton.style.minWidth = "3%";
pauseButton.style.fontSize = "80%";
pauseButton.textContent = "Pause"
pauseButton.addEventListener('click', function() {toggleButton(job, item, kundeItem, this.id)});
timerList.appendChild(pauseButton);
}
else if (statusTimer[i].value === "Paused") {
var pauseButton = document.createElement('button')
pauseButton.id = i;
pauseButton.classList.add('pauseButton');
pauseButton.style.position = "fixed";
pauseButton.style.top = (12 + i * 14) + "%";
pauseButton.style.left = "90%";
pauseButton.style.height = "9.4%";
pauseButton.style.minWidth = "3%";
pauseButton.style.fontSize = "80%";
pauseButton.textContent = "Start"
pauseButton.addEventListener('click', function() {toggleButton(job, item, kundeItem, this.id)});
timerList.appendChild(pauseButton);
}

//----Stop Button mit dynamisch vergebener ID wird ausgegeben----//

var stopButton = document.createElement('button')
stopButton.id = i;
stopButton.classList.add('stopButton');
stopButton.style.position = "fixed";
stopButton.style.top = (12 + i * 14) + "%";
stopButton.style.left = "94%";
stopButton.style.height = "9.4%";
stopButton.style.width = "3%";
stopButton.style.fontSize = "80%";
stopButton.textContent = "Stop"
stopButton.addEventListener('click', function() {stopTimer(job, item, kundeItem, index, this.id)});
timerList.appendChild(stopButton);

//----Für jeden aufgerufenen Timer wird----//
//----eine neue Reihe ausgegeben----//

timerList.appendChild(neueReihe);
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//-----------------------------------------------Sekunden in Uhrzeit umrechnen-------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Rechnet übergebene Sekunden in Stunden,----//
//----Minuten und Sekunden und gibt diese----//
//----an aufrufende Funktion zurück----//

function formatElapsedTime(seconds) {

var minutes = Math.floor(seconds / 60);
seconds %= 60;
var hours = Math.floor(minutes / 60);
minutes %= 60;
function addLeadingZero(n) {
return (n < 10 ? '0' : '') + n;
}

return addLeadingZero(hours) + ":" + addLeadingZero(minutes) + ":" + addLeadingZero(seconds);
}

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------Uhrzeit in Sekunden umrechnen----------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Rechnet übergebene Stunden, Minuten----//
//----und Sekunden in Sekunden um und----//
//----gibt diese an aufrufende Funktion zurück----//

function timeInSeconds(zeit) {

var teile = zeit.split(':');
var Stunden = parseInt(teile[0], 10);
var Minuten = parseInt(teile[1], 10);
var Sekunden = parseInt(teile[2], 10);
return Stunden * 3600 + Minuten * 60 + Sekunden;
}

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------------Lightbox-------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Öffnet eine Lightbox und zeigt Kunde----//
//----Job, vergangene Zeit und evtl Pausenzeit an----//
//----und gibt Möglichkeit alle Zeiten anzupassen----//

function openLightbox(job, item, kundeItem, index, id) {

document.getElementById('lightbox').style.display = 'block';

var dateField = document.getElementById("date");
dateField.value = datum[id].value;
document.getElementById("uhrzeit").innerHTML = uhrzeit[id].value;

var commentTextarea = document.getElementById("comment");
commentTextarea.value = selectedJob[id].value;

document.getElementById("eingPersonZusatz").innerHTML = selectedKunde[id].value;

if (selectedID.length !== undefined) {
document.getElementById("eingPerson").innerHTML = selectedID;
}
else {
document.getElementById("eingPerson").innerHTML = selID[id].value;
}

//----Ausgabe der vergangenen Zeit in Lightbox----//

document.getElementById("outStd").value = 00;
document.getElementById("outMin").value = 00;
document.getElementById("outSek").value = 00;

//----Ausgabe der Pausenzeiten in Lightbox----//

document.getElementById("outStd2").value = 00;
document.getElementById("outMin2").value = 00;
document.getElementById("outSek2").value = 00;
getPauseTime(sys_uid[id].value, id);

var secondsPause = pauseTime[id].value;
secondsPause %= 60;

var minutesPause = Math.floor(pauseTime[id].value / 60);
minutesPause %= 60;

var hoursPause = Math.floor(minutesPause / 60);
hoursPause %= 60;

document.getElementById("outStd2").value = hoursPause;
document.getElementById("outMin2").value = minutesPause;

if (secondsPause > 0) {
document.getElementById("outSek2").value = secondsPause;
}
else {
document.getElementById("outSek2").value = 0;
}

var dropdown2 = document.getElementById("tätigkeit2Dropdown");

job.forEach(function(item, index) {
var option = document.createElement("option");
option.textContent = item;
dropdown2.add(option)

if (item === selectedJob[id].value) {
option.selected = true;
}
});

document.addEventListener('keydown', closeLightboxOnEscape);
document.addEventListener('keydown', closeLightboxOnF2);
}

//----Lightbox schließen----//

function closeLightbox() {

document.getElementById('lightbox').style.display = 'none';
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn der Schließen-Button gedrückt wird----//

function closeLightboxOnSchliessen() {

statusTimer[idStop].value = 'Running';
closeLightbox();
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn Escape gedrückt wird----//

function closeLightboxOnEscape() {

if (event.key === 'Escape') {
statusTimer[idStop].value = 'Running';
closeLightbox();
}
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn F2 gedrückt wird----//

function closeLightboxOnF2(event) {

if (event.key === 'F2') {
saveBox();
closeLightbox();
}
}

//----Alle Daten in Lightbox werden gespeichert----//

function saveBox() {

var vergZeit = '"' + time + '"';

var teile = time.split(":");
var stunden = parseInt(teile[0]);
var minuten = parseInt(teile[1]);
var sekunden = parseInt(teile[2]);
time = stunden * 3600 + minuten * 60 + sekunden;

elapsedTime = time;

var comment = '"' + document.getElementById("comment").value + '"';

var hPEnd = document.getElementById("outStd2").value;
var mPEnd = document.getElementById("outMin2").value;
var sPEnd = document.getElementById("outSek2").value;
var pTime = hPEnd + ":" + mPEnd + ":" + sPEnd;
pTime = timeInSeconds(pTime);

var uid = sys_uid[idStop].value;
var month = startTimeValue.getMonth();
var day = startTimeValue.getDate();
month += 1;
var stopTimeValue = '"' + startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + (day < 10 ? "0" + day : day) + '"';

var status = 21;

timers.splice(idStop, 1);
pauseTimers.splice(idStop, 1);
pauseTime.splice(idStop, 1);
selectedKunde.splice(idStop, 1);
selectedJob.splice(idStop, 1);
statusTimer[idStop].value = 'Running';
sys_uid.splice(idStop, 1);

if (zaehler > 0) {
zaehler -= 1;
}

closeLightbox();

if (timers.length === 0) {
clearInterval(timerInterval);
}

saveStopTime(stopTimeValue, elapsedTime, pTime, status, uid, vergZeit, comment);
}

//----Funktion saveBox wird aufgerufen,----//
//----wenn der Save-Button gedrückt wird----//

document.addEventListener('DOMContentLoaded', function() {
const saveButton = document.getElementById('saveButton');
saveButton.addEventListener('click', function() {
saveBox();
})
});
</syntaxhighlight>

= PHP-Script saveTime.php =
<syntaxhighlight lang="php">
<?php
$user = 0;
$uhrzeit = 0;
$datum = 0;
$endTime = 0;
$endDate = 0;
$status = 0;
$psnr = 0;
$comm = 0;
$jobID = 0;
$pauseTime = 0;
$sysuid = 0;
$stopTimeValue = 0;
$elapsedTime = 0;
$elapsedPauseTime = 0;
$status = 0;
$uid = 0;
$vergZeit = 0;

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$api_key = $_POST['api_key'];
$url = $_POST['url'];
$method = $_POST['method'];
$choice = $_POST['choice'];

if (isset($_POST['user'])) {
$user = $_POST['user'];
}
if (isset($_POST['uhrzeit'])) {
$uhrzeit = $_POST['uhrzeit'];
}
if (isset($_POST['datum'])) {
$datum = $_POST['datum'];
}
if (isset($_POST['endTime'])) {
$endTime = $_POST['endTime'];
}
if (isset($_POST['endDate'])) {
$endDate = $_POST['endDate'];
}
if (isset($_POST['status'])) {
$status = $_POST['status'];
}
if (isset($_POST['psnr'])) {
$psnr = $_POST['psnr'];
}
if (isset($_POST['Job'])) {
$comm = $_POST['Job'];
}
if (isset($_POST['jobID'])) {
$jobID = $_POST['jobID'];
}
if (isset($_POST['pauseTime'])) {
$pauseTime = $_POST['pauseTime'];
}
if (isset($_POST['sysuid'])) {
$sysuid = $_POST['sysuid'];
}
if (isset($_POST['stopTimeValue'])) {
$stopTimeValue = $_POST['stopTimeValue'];
}
if (isset($_POST['elapsedTime'])) {
$elapsedTime = $_POST['elapsedTime'];
}
if (isset($_POST['elapsedPauseTime'])) {
$elapsedPauseTime = $_POST['elapsedPauseTime'];
}
if (isset($_POST['status'])) {
$status = $_POST['status'];
}
if (isset($_POST['uid'])) {
$uid = $_POST['uid'];
}
if (isset($_POST['vergZeit'])) {
$vergZeit = $_POST['vergZeit'];
}

$params = array( 'user' => $user,
'uhrzeit' => $uhrzeit,
'datum' => $datum,
'endTime' => $endTime,
'endDate' => $endDate,
'status' => $status,
'psnr' => $psnr,
'comm' => $comm,
'jobID' => $jobID,
'pauseTime' => $pauseTime,
'sysuid' => $sysuid,
'stopTimeValue' => $stopTimeValue,
'elapsedTime' => $elapsedTime,
'elapsedPauseTime' => $elapsedPauseTime,
'status' => $status,
'uid' => $uid,
'vergZeit' => $vergZeit,
'choice' => $choice);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('apikey: '.$api_key));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($params));
$response = curl_exec($curl);

if ($response === false) {
if($error) {
echo "curl_Fehler: ".$error;
}
}
else {
echo $response;
}
}
?>
</syntaxhighlight>

= PHP-Script getData.php =
<syntaxhighlight lang="php">
<?php
$sysuid = 0;
$id = 0;
$selectedKunde = 0;

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$api_key = $_POST['api_key'];
$url = $_POST['url'];
$method = $_POST['method'];
$choice = $_POST['choice'];

if (isset($_POST['id'])) {
$id = $_POST['id'];
}
if (isset($_POST['sysuid'])) {
$sysuid = $_POST['sysuid'];
}
if (isset($_POST['selectedKunde'])) {
$selectedKunde = $_POST['selectedKunde'];
}

$params = array( 'sysuid' => $sysuid,
'id' => $id,
'selectedKunde' => $selectedKunde,
'choice' => $choice);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('apikey: '.$api_key));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($params));
$response = curl_exec($curl);

if ($response === false) {
if($error) {
echo "curl_Fehler: ".$error;
}
}
else {
echo $response;
}
}
?>
</syntaxhighlight>

= CSS-Datei timestyle.css =
<syntaxhighlight lang="css">
/*-------------------------------------------------------------------------------------------------*/
/*-----------------------------------------Allgemein-----------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

body
{
font-family: 'Arial', sans-serif;
display: flex;
justify-content: right;
align-items: flex-start;
height: 100%;
background-image: url('web_background_3.png');
background-repeat: no-repeat;
background-size: cover;
background-attachment: fixed;
}
ul
{
list-style-type: none;
}
li
{
padding: 0.5em;
cursor: pointer;
display: flex;
justify-content: space-between;
align-items: center;
font-size: 0.85em;
}

/*-------------------------------------------------------------------------------------------------*/
/*-------------------------------------------Suche-------------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

#search
{
position: fixed;
top: 8%;
left: 42%;
width: 15%;
height: 2.8%;
resize: none;
border: 0.04em solid #e4e4e4;
border-radius: 0.1em;
background-color: white;
font-size: 2em;
overflow: hidden;
}

/*-------------------------------------------------------------------------------------------------*/
/*-----------------------------------------Timerausgabe--------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

.kundenliste
{
width: 70%;
height: 30%;
position: fixed;
top: 43.5%;
left: 50%;
transform: translate(-50%, -50%);
border-top-left-radius: 0.2em;
border-top-right-radius: 0.2em;
overflow: auto;
background-color: white;
font-size: 0.85vw;
}
.tabelleUeberschriften
{
width: 70%;
min-height: 3%;
position: fixed;
top: 60%;
left: 50%;
transform: translate(-50%, -50%);
/* border-top: 0.14em solid #ccc;
border-bottom: 0.14em solid #ccc; */
background-color: white;
box-shadow: 0 0px 3px rgba(0, 0, 0, 0.5);
font-size: 0.9vw;
}
#timerList
{
width: 70%;
height: 25%;
position: fixed;
top: 73.5%;
left: 50%;
transform: translate(-50%, -50%);
overflow: auto;
border-bottom-left-radius: 0.2em;
border-bottom-right-radius: 0.2em;
/* border: 0.14em solid red; */
background-color: white;
font-size: 0.85vw;
}
.kunde
{
width: 30%;
position: fixed;
left: 0%;
}
.konto
{
width: 30%;
position: fixed;
left: 30%;
}
.laufzeit
{
width: 15%;
position: fixed;
left: 60%;
}
.status
{
width: 15%;
position: fixed;
left: 75%;
}
.buttons
{
width: 10%;
position: fixed;
left: 90%;
}

/*-------------------------------------------------------------------------------------------------*/
/*-------------------------------------------Lightbox----------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

.lightbox
{
display: none;
width: 52%;
height: 62%;
position: fixed;
top: 61.5%;
left: 67%;
border-radius: 0.15em;
background-color: white;
transform: translate(-50%, -50%);
flex-direction: column;
align-items: center;
box-shadow: 0 10px 2000px rgba(0, 0, 0, 0.5);
}

/*-----------------------------------------Lightbox-Inhalt-----------------------------------------*/

.commLabel
{
position: fixed;
top: 5%;
left: 5%;
font-weight: bold;
font-size: 0.8vw;
}
.comment
{
width: 90%;
height: 38%;
position: fixed;
top: 10%;
left: 5%;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.9vw;
}

.bezZeitkonto
{
position: fixed;
top: 55%;
left: 5%;
font-size: 0.8vw;
}
.dropButtonsLightbox
{
width: 37%;
height: 4.4%;
position: fixed;
top: 54%;
left: 15%;
font-size: 0.7vw;
}
.bezDatum
{
position: fixed;
top: 55%;
left: 58%;
font-size: 0.7vw;
}
.date
{
position: fixed;
top: 54%;
left: 68%;
width: 15%;
height: 4%;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
}
.uhrzeit
{
position: fixed;
top: 54%;
left: 85.5%;
width: 10%;
height: 3.9%;
padding: 0.1em;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
resize: none;
}

.bezPerson
{
position: fixed;
top: 68%;
left: 5%;
font-size: 0.8vw;
}
.eingPerson
{
position: fixed;
top: 68%;
left: 15%;
width: 10%;
height: 4.4%;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
}
.eingPersonZusatz
{
position: fixed;
top: 68%;
left: 26%;
width: 25.7%;
height: 4.4%;
overflow: auto;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
}
.Std
{
position: fixed;
top: 63%;
left: 66%;
font-size: 0.7vw;
}
.Min
{
position: fixed;
top: 63%;
left: 78%;
font-size: 0.7vw;
}
.Sek
{
position: fixed;
top: 63%;
left: 91%;
font-size: 0.7vw;
}
.outStd
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 64%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outMin
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 76.5%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outSek
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 89%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}

.Pausenzeiten
{
position: absolute;
top: 79%;
left: 71%;
font-weight: bold;
font-size: 0.8vw;
}
.Std2
{
position: fixed;
top: 84%;
left: 66%;
font-size: 0.7vw;
}
.Min2
{
position: fixed;
top: 84%;
left: 78%;
font-size: 0.7vw;
}
.Sek2
{
position: fixed;
top: 84%;
left: 91%;
font-size: 0.7vw;
}
.outStd2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 64%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outMin2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 76.5%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outSek2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 89%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.saveButton
{
min-width: 8%;
height: 4.4%;
position: fixed;
top: 89%;
left: 5%;
font-size: 0.7vw;
}
.closeButton
{
min-width: 8%;
height: 4.4%;
position: fixed;
top: 89%;
left: 14%;
font-size: 0.7vw;
}

/*-------------------------------------------------------------------------------------------------*/
/*--------------------------------Tätigkeitenliste (zweite Liste)----------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

#zweiteListe
{
display: none;
width: 25%;
max-height: 50%;
position: fixed;
top: 47%;
left: 44%;
padding: 1%;
overflow: auto;
border-radius: 0.2em;
transform: translate(-50%, -50%);
background-color: #FAFAFA;
box-shadow: 0 10px 2000px rgba(0, 0, 0, 0.5);
font-size: 0.85vw;
}

</syntaxhighlight>

OBS/Kostenpflichtige Module/RESTServer/Scripting

2026-09-01T09:10:11Z

Rademacker:

{{Kostenpflichtige Module}}

=Anleitung für Endpunkt-Skripte=

Jede Anfrage an einen Endpunkt wird nach erfolgreicher Authentifizierung und Autorisierung an das hinterlegte Skript weitergegeben. Das Skript ist in Object Pascal geschrieben und greift auf die OBS-Bibliothek (DB-Zugriff, Hilfsfunktionen) zu.

==Sicherheitshinweise==

{{Hinweis|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Übergabeparameter dürfen niemals ungeprüft in SQL-Anweisungen eingebaut werden. Werte immer über ''DB_SQLVal'' bzw. Parameter-Bindings absichern, Eingabewerte gegen Whitelists prüfen.}}

* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
* Nur das zurückgeben, was der Konsument wirklich braucht - keine internen IDs, keine Sys-Felder, keine Passwörter.
* Bei Fehlern keine internen Details an den Konsumenten zurückgeben; stattdessen schreibt der Server ohnehin Detail-Einträge in '''RESTSRV_PROTO'''.

==Methoden-Signatur==

Pro HTTP-Methode wird im Skript eine gleichnamige Funktion implementiert. Der Server ruft genau die Funktion auf, die zur Methode des eingehenden Requests passt.

function Get (oParams: TStrings; oBody: TJSONObject): string;
function Post (oParams: TStrings; oBody: TJSONObject): string;
function Put (oParams: TStrings; oBody: TJSONObject): string;
function Delete(oParams: TStrings; oBody: TJSONObject): string;
function Patch (oParams: TStrings; oBody: TJSONObject): string;

Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
Not Allowed''' (<code>METHOD_NOT_ALLOWED</code>) und nennt im Header
<code>Allow</code> die Verben, die dieses Skript tatsächlich anbietet - die Liste
stammt aus dem kompilierten Skript und kann deshalb nicht veralten:

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT

Ein im Vertrag zugesagtes Verb braucht also seine Funktion. Fehlt sie, ist das an
der Antwort sofort zu erkennen und '''kein''' Serverfehler.

==Parameter==

===oParams (TStrings)===

Enthält alle Query-Parameter, POST-Parameter (form-urlencoded) sowie die durchgereichten HTTP-Header. Werte sind immer Strings.

Filterung durch den Server:

* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
* Parameter mit Präfix '''_OBS_''' können von aussen nicht gesetzt werden; sie sind für interne Werte reserviert.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.

Zugriff im Skript:

if (not Empty(oParams.Values['kundennr'])) then begin
cKundenNr := oParams.Values['kundennr'];
end;

===oBody (TJSONObject)===

Enthält den Request-Body, sofern dieser ein gültiges JSON-Objekt ist. Bei leerem oder nicht-JSON-Body wird ''nil'' übergeben.

{{Hinweis|'''Generics funktionieren im Skript nicht.''' Aus Delphi bekannte
Schreibweisen wie ''oBody.TryGetValue<string>('feld', cVar)'' lassen sich nicht
übersetzen. Gelesen wird über ''GetValue''.}}

''GetValue'' liefert ''nil'', wenn das Feld im Body '''nicht enthalten''' ist -
daran lässt sich „nicht gesendet" von „leer gesendet" unterscheiden. Der Wert ist
immer ein '''String''' und wird bei Bedarf selbst gewandelt.

cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username');
if (Assigned(oVal)) then begin
cUser := oVal.Value;
end;
oVal := oBody.GetValue('password');
if (Assigned(oVal)) then begin
cPass := oVal.Value;
end;
end;

Bei mehr als zwei Feldern lohnt eine kleine Hilfsfunktion, die das Muster einmal
kapselt:

<syntaxhighlight lang="pascal" line>
function _BodyStr(oBody: TJSONObject; const cFeld: string): string;
var oVal: TJSONValue;
begin
result := '';
if (oBody = nil) then begin
exit;
end;
oVal := oBody.GetValue(cFeld);
if (Assigned(oVal)) then begin
result := oVal.Value;
end;
end;

// Aufruf:
cBetreff := _BodyStr(oBody, 'betreff');
</syntaxhighlight>

Andere Typen entstehen aus dem String:

{| class="wikitable"
! Zieltyp !! Umwandlung
|-
| Ganzzahl || <code>iVal(_BodyStr(oBody, 'menge'))</code>
|-
| Kommazahl || <code>fVal(StrTran(_BodyStr(oBody, 'preis'), '.', ','))</code> - '''JSON liefert den Dezimalpunkt''', ''fVal'' erwartet die lokale Notation
|-
| Boolean || <code>Lower(_BodyStr(oBody, 'aktiv')) = 'true'</code>
|-
| Datum/Zeit || ISO-8601-String selbst zerlegen (''CToDT'' erwartet das deutsche Format)
|}

Maximale Body-Grösse: 10 MB.

===Reservierte _OBS_-Parameter===

Bei aktiver JWT-Authentifizierung stehen die Token-Claims als Parameter zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_JWT_ID || JWT-Id (''jti''-Claim) - typisch die User-Id. '''Muss nicht eindeutig sein''': die Sitzung führt der Server über eigene Kennungen (siehe unten)
|-
| _OBS_JWT_SUBJECT || Subject (''sub''-Claim) - typisch Benutzername
|-
| _OBS_JWT_AUDIENCE || Audience (''aud''-Claim) - typisch Mandant / Rolle
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim des Tokens (z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles); im Folge-Skript lesbar
|-
| _OBS_TRACE_ID || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}

Unabhängig von JWT stehen ausserdem immer zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_SERVER_TIME || Aktuelle Serverzeit als ISO-8601 '''mit UTC-Offset''' (z.B. ''2026-08-17T09:12:33+02:00''). Nützlich, um Datumswerte in derselben Zeitzone auszuliefern, in der der Server arbeitet, und damit ein Client seinen Uhren-Versatz bestimmen kann
|-
| _OBS_JWT_EXP_SEC || Laufzeit des Access-Tokens in Sekunden (''JWT-Exp'' × 60). Damit kann ein Konfigurations-Endpunkt denselben Wert ausliefern, den der Token wirklich hat
|}

Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.

Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
''_OBS_JWT_CLAIM_sid'' und ''_OBS_JWT_CLAIM_rid'':

{| class="wikitable"
! Claim !! Inhalt
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
|}

Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Skripts gesetzt - ein Skript kann sie also auch mit ''_OBS_JWT_CLAIM_sid'' nicht
überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.

===Pfad-Parameter===

Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte als reservierte Parameter mit Präfix '''_OBS_PATH_''' in ''oParams'' bereit:

{| class="wikitable"
! Template !! Zugriff im Skript
|-
| <code>/orders/{uid}</code> || ''oParams.Values['_OBS_PATH_uid']''
|-
| <code>/orders/{uid}/modules/{code}</code> || ''oParams.Values['_OBS_PATH_uid']'', ''oParams.Values['_OBS_PATH_code']''
|}

Da der Präfix ''_OBS_'' für von aussen gelieferte Header- und Query-Parameter gesperrt ist, sind diese Werte nicht durch den Client fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].

===Datei-Uploads===

Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), nimmt der Server
hochgeladene Dateien entgegen, legt sie in einem temporären Verzeichnis ab und
übergibt dem Skript Pfad, Originalname und Content-Type über reservierte
Parameter. Das Skript entscheidet selbst über die weitere Verarbeitung (z.B.
DMS-Ablage). Der Body wird in diesem Fall '''nicht''' als JSON geparst - ''oBody''
ist ''nil''. Es gilt nicht das JSON-Body-Limit (10 MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25 MB;
Überschreitung -> 413).

Beide Übertragungsarten - <code>multipart/form-data</code> und der resumable
<code>Content-Range</code>-Upload - liefern dem Skript dieselben Parameter:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_UPLOAD_PATH || Vollständiger Pfad zur temporären Datei auf dem Server
|-
| _OBS_UPLOAD_NAME || Originaldateiname
|-
| _OBS_UPLOAD_CONTENTTYPE || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt)
|-
| _OBS_UPLOAD_SHA256 || SHA-256 der '''gespeicherten''' Datei, hex in Kleinbuchstaben. Damit lässt sich eine vom Client mitgesendete Prüfsumme vergleichen - erst dieser Vergleich macht aus ihr eine Zusicherung
|}

Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''_OBS_UPLOAD_PATH'' und ''_OBS_UPLOAD_NAME''
gesetzt sind, sobald es läuft.

{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}

====Einfacher Upload (multipart/form-data)====

Eine Datei pro Request. Name und Content-Type stammen aus der
<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
Server speichert die erste Datei-Partie und ruft das Skript auf.

Die '''übrigen Partien''' des Formulars - alles ohne <code>filename=</code> -
übergibt der Server als <code>_OBS_FORM_<name></code>. Der Wert ist UTF-8 und
auf 1024 Zeichen begrenzt, der Name auf Buchstaben, Ziffern und Unterstrich
reduziert. Zusatzangaben lassen sich damit im selben Request mitschicken, ohne sie
an die URL zu hängen:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cPfad: string;
cName: string;
cTyp : string;
begin
oRes := TJSONObject.Create();
try
cPfad := oParams.Values['_OBS_UPLOAD_PATH'];
cName := oParams.Values['_OBS_UPLOAD_NAME'];
cTyp := oParams.Values['_OBS_UPLOAD_CONTENTTYPE'];

// ... Datei aus cPfad ins DMS / Zielverzeichnis uebernehmen ...

oRes.AddPair('status' , 'ok');
oRes.AddPair('dateiname', cName);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

====Resumable/Chunked Upload (Content-Range)====

Für grosse Dateien überträgt der Client die Datei in Teilstücken (Chunks) mit dem
Header <code>Content-Range: bytes START-END/TOTAL</code>. Der Server hängt die
Chunks '''sequentiell''' an eine Session-Datei an und behandelt unvollständige
Uploads selbst - das Endpunkt-Skript läuft '''erst beim vollständigen Upload'''
(dann mit gesetztem ''_OBS_UPLOAD_PATH'', ''_OBS_UPLOAD_NAME'' und
''_OBS_UPLOAD_CONTENTTYPE'').

Name und Content-Type sind im <code>Content-Range</code>-Protokoll nicht enthalten;
der Client liefert sie deshalb '''im ersten Chunk''' über den Header
<code>Upload-Metadata</code> (Format wie bei tus: kommagetrennte Paare
<code>schlüssel base64wert</code>, Werte Base64-kodiert):

<pre>
Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm
</pre>

Erkannt werden die Schlüssel <code>filename</code> (Pflicht) und
<code>filetype</code> (optional). Fehlt <code>filename</code> im ersten Chunk,
wird der Upload mit '''400''' abgelehnt, ohne dass eine Datei angelegt wird.
Folge-Chunks und Statusabfragen müssen die Metadaten nicht erneut senden.

Ablauf (vom Client gesteuert, der Server antwortet jeweils):

{| class="wikitable"
! Request !! Server-Antwort
|-
| Erster Chunk <code>Content-Range: bytes 0-1048575/5000000</code> + <code>Upload-Metadata</code> || '''308''' Resume Incomplete + Header <code>Upload-Id</code>, <code>Upload-Offset</code>, <code>Range</code>
|-
| weitere Chunks (jeweils <code>Upload-Id</code> mitsenden) || '''308''' mit aktualisiertem <code>Upload-Offset</code>
|-
| letzter Chunk (Bereich erreicht TOTAL) || normale Skript-Antwort (z.B. '''200'''/'''201''')
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> || aktueller <code>Upload-Offset</code>, ohne anzuhängen (Resume)
|}

{| class="wikitable"
! Header !! Richtung !! Bedeutung
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
|-
| Upload-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
|-
| Upload-Id || Request/Response || Session-Kennung. Fehlt sie im ersten Request, erzeugt der Server eine und gibt sie zurück; alle Folge-Chunks müssen sie mitsenden.
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
|}

Der Server hängt einen Chunk '''nur an, wenn START dem bereits gespeicherten Stand
entspricht'''. Bei Abweichung (doppelter Chunk, Lücke) wird nicht angehängt,
sondern der aktuelle ''Upload-Offset'' zurückgemeldet - der Client setzt ab dort
neu auf. Eine separate Statusabfrage ist für ein Resume daher nicht zwingend nötig.

Überschreitet ein Chunk bzw. die Gesamtgrösse das Limit (''re_upload_size''),
antwortet der Server mit '''413 Payload Too Large'''.

{{Hinweis|Der Upload-Status liegt prozesslokal im Speicher. Nach einem Neustart des Servers muss ein unvollständiger Upload neu begonnen werden.}}

==Rückgabe==

Die Rückgabe ist immer ein '''JSON-String'''. Wird ein leerer String zurückgegeben, antwortet der Server automatisch mit ''{}''. Der Server setzt Content-Type auf ''application/json; charset=utf-8'' und Status auf 200, sofern das Skript nicht selbst einen Fehler signalisiert.

Einfaches Beispiel:

<syntaxhighlight lang="pascal" line>
function Get(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
oRes := TJSONObject.Create();
try
oRes.AddPair('wert_string', '123');
oRes.AddPair('wert_int' , 456);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Antwort steuern: Statuscode, Header, traceId==

Ein Skript kann den HTTP-Statuscode und beliebige Response-Header über reservierte Felder in der Antwort setzen. Der Server wertet sie aus und entfernt sie vor dem Senden aus dem Body.

{| class="wikitable"
! Antwort-Feld !! Wirkung
|-
| _OBS_HTTP_STATUS (Zahl) || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200. Bei 204 wird kein Body gesendet.
|-
| _OBS_HEADERS (Objekt) || Beliebige Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen/Werten werden entfernt (Schutz vor Header-Injection).
|-
| _OBS_JWT_REVOKE (Text) || Sperrt die Sitzung des vorgelegten Tokens (''session'') oder alle Sitzungen des Subjects (''all''). Damit wird ein Endpunkt zum Logout, ohne eigene Verwaltung. Scheitert das Sperren, antwortet der Server mit '''503''' statt mit der Antwort des Skripts - siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Abschnitt Abmelden.
|}

Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oParams.Values['_OBS_TRACE_ID']'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

===Beispiel: Anlegen mit 201, Location und ETag===

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
// ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...
oHdr := TJSONObject.Create();
oHdr.AddPair('Location', '/v1/orders/' + cNeueUid);
oHdr.AddPair('ETag', '1');

oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('uid', cNeueUid);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Beispiel: Strukturierter Fehler mit Statuscode und traceId===

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
oErr := TJSONObject.Create();
oErr.AddPair('code', 'VALIDATION_FAILED');
oErr.AddPair('message', 'Feld "menge" fehlt');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Beispiel: Optimistic Concurrency (ETag / If-Match)===

Mit Statuscode, Headern und dem lesbaren Header ''If-Match'' führt das Skript je Datensatz einen Versionszähler und lehnt veraltete Schreibzugriffe mit 409 ab:

<syntaxhighlight lang="pascal" line>
function Put(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
nAktuell, nIfMatch: integer;
begin
oRes := TJSONObject.Create();
try
nAktuell := AuftragVersion(oParams.Values['_OBS_PATH_uid']);
nIfMatch := iVal(oParams.Values['if-match']);

if (nIfMatch <> nAktuell) then begin
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell));
oRes.AddPair('_OBS_HTTP_STATUS', 409);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'VERSION_CONFLICT'));
result := oRes.ToJSON();
exit;
end;

// ... speichern, Version hochzählen ...
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell + 1));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Idempotenz - was das Skript beachten muss==

Sendet ein Konsument bei ''POST''/''PUT''/''PATCH''/''DELETE'' den Header
<code>Idempotency-Key</code>, fängt der '''Server''' doppelte Sendungen ab. Das
Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine
Prüfung am Anfang der Methode.

Was das Skript wissen muss:

{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
|-
| '''2xx''' || Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
|-
| '''5xx''' oder Exception || Der Schlüssel bleibt belegt, der Fall wird protokolliert. Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist
|}

Daraus folgen zwei Regeln für Endpunkt-Skripte:

* '''Fachliche Ablehnungen als 4xx melden''' (422, 409, 404), nicht als 2xx mit Fehlertext im Body. Sonst wird die Ablehnung gespeichert und der Konsument bekommt sie bei jedem weiteren Versuch erneut - auch nachdem er den Fehler behoben hat.
* '''Die Antwort muss vollständig sein.''' Was zurückgegeben wird, wird eingefroren. Ein Feld, das erst der zweite Aufruf ergänzen würde, kommt beim Konsumenten nie an.

{{Hinweis|Vor dieser Server-Funktion mussten Skripte die Idempotenz selbst
abbilden. Solche Skripte laufen unverändert weiter - die Doppelprüfung schadet
nicht, ist aber überflüssig und kann beim nächsten Überarbeiten entfallen.}}

Der vollständige Ablauf und die Statuscodes stehen unter
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==JWT-Authentifizierungs-Skript==

Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser : string;
cPass : string;
begin
oRes := TJSONObject.Create();
try
// Eingangsdaten lesen (Body oder Query-Param)
cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username');
if (Assigned(oVal)) then begin
cUser := oVal.Value;
end;
oVal := oBody.GetValue('password');
if (Assigned(oVal)) then begin
cPass := oVal.Value;
end;
end;

// Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
if (PasswortPasst(cUser, cPass)) then begin
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT', cUser);
oRes.AddPair('_OBS_JWT_AUDIENCE', 'mandant1');
end else begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Login fehlgeschlagen');
end;

result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

Rückgabewerte:

{| class="wikitable"
! status !! Bedeutung
|-
| 1 || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
|-
| 9 || Misserfolg, der Server antwortet mit '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
|}

{{Hinweis|Der Text aus ''error'' geht bei ''status'' = 9 '''an den Konsumenten'''
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Endanwender verständlich sein und keine internen Details verraten.}}

Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
„Passwort falsch" erscheinen.

Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.

===Aufbau der Token-Antwort===

Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
Feldern, die das Skript zurückgibt''':

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...",
"accessToken": "eyJ...",
"refreshToken":"eyJ...",
"expiresIn": 28800,
"serverTime": "2026-08-17T09:12:33+02:00"}

{| class="wikitable"
! Feld !! Herkunft
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
|-
| serverTime || Serverzeit ISO-8601 mit Offset
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
|}

Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.

===Custom-Claims, serverTime und Refresh===

Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:

{| class="wikitable"
! RÜckgabefeld !! Bedeutung
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als oParams.Values['_OBS_JWT_CLAIM_<name>'].
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
|}

Jedes Token trägt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh'') sowie die Sitzungskennungen ''sid'' und ''rid'' des Servers. Die Antwort enthält bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusätzlich ''refreshToken'':

{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}

{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''_OBS_JWT_CLAIM_*''), nie aus Body oder Query.}}

====Refresh-Methode====

Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
(Signatur, Ablauf, ''token_use=refresh'') und in der Sitzung '''entwertet'''.
Einmalgebrauch, Rotation und Sperrliste sind damit Sache des Servers. Das Skript
liefert nur noch die aktuellen Claims - genau das ist der Sinn des Aufrufs: eine
zwischenzeitlich geänderte Rolle oder ein gewechselter Mandant wirken spätestens
mit der nächsten Erneuerung.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal - einmal im Skript, einmal im
Server - und riskiert, dass beide Seiten unterschiedlicher Meinung sind. Der
Server sieht die Skript-Tabelle nicht, und das Skript sieht die Sitzung nicht.}}

Ein bereits benutztes Refresh-Token wird mit '''401''' abgelehnt. Erfolgt die
erneute Vorlage innerhalb von 60 Sekunden, bleibt die Sitzung bestehen (paralleler
Refresh einer App); danach gilt sie als Wiedervorlage und die '''gesamte Sitzung
wird gesperrt'''. Details in [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

Das alte Refresh-jti steht weiterhin als ''oParams.Values['_OBS_JWT_ID']'' bereit,
falls das Skript es für eigene Protokollierung braucht.

<syntaxhighlight lang="pascal" line>
function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cUser: string;
begin
oRes := TJSONObject.Create();
try
cUser := oParams.Values['_OBS_JWT_SUBJECT'];

// Der Server hat das vorgelegte Refresh-Token bereits geprueft und
// entwertet. Hier wird nur entschieden, ob der Benutzer die Sitzung
// fortsetzen darf - und mit welchen Rechten.
if (not BenutzerAktiv(cUser)) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
result := oRes.ToJSON();
exit;
end;

// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das neue Refresh-Token aus
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Abmelden (Logout)===

'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Phase 4.

Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
'''gewöhnlichen Endpunkt''' und setzt dort ''_OBS_JWT_REVOKE''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
oRes := TJSONObject.Create();
try
GeraeteRegistrierungLoeschen(oParams.Values['_OBS_JWT_SUBJECT']);

// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
oRes.AddPair('_OBS_JWT_REVOKE' , 'session');
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
abgemeldet, während sein Token weiterläuft.

==Fehlerbehandlung im Skript==

Tritt im Skript eine Exception auf oder schlägt die Syntax-Prüfung fehl, antwortet der Server mit 500 ''Interner Fehler'' und protokolliert die Detail-Meldung in '''RESTSRV_PROTO''' (mit Skript-Fehlertext). Der Konsument sieht keine internen Details.

Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Will das Skript einen spezifischen Fehler an den Konsumenten zurückgeben, sollte es
'''dasselbe Format und einen passenden Statuscode''' verwenden:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
if (Empty(oParams.Values['kundennr'])) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'Parameter ''kundennr'' fehlt');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;
// ...
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
Body auszuwerten - und nur so gibt der Server einen belegten
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}

===Ändern: qSqlInit statt qSqlRead===

Zum '''Ändern''' eines vorhandenen Satzes wird ebenfalls <code>qSqlInit</code>
benutzt - der Satz wird über <code>sys_uid</code> adressiert:

<syntaxhighlight lang="pascal" line>
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cSysUid); // Schreib-Index auf den Originalsatz
q.qSet('ti_status', '9');
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln, siehe unten
end;
qSqlFree(q);
</syntaxhighlight>

<code>qSqlRead</code> ist dafür die falsche Wahl, aus zwei Gründen:

* Es liest den '''kompletten Altsatz''' ein - ein zusätzlicher Lesezugriff, der Zeit kostet.
* Es schreibt anschliessend nur die '''Änderungen'''. Ist der neue Wert gleich dem alten, entsteht gar kein Write, und <code>SaveData</code> liefert '''False''' - ununterscheidbar von einem echten Fehlschlag.

{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen'''
Datensatz an, statt den vorhandenen zu ändern. Die <code>sys_uid</code> ist der
Schreib-Index und gehört bei jeder Änderung gesetzt.}}

Damit entfällt auch das übliche Paar aus <code>DB_LSeek</code> und
<code>qSqlRead</code>: '''eine''' Abfrage auf die <code>sys_uid</code> liefert
zugleich die Existenzprüfung und den Schreib-Index.

<syntaxhighlight lang="pascal" line>
cUid := '';
if (DB_SOpen(oDB, 'SELECT sys_uid FROM tickets WHERE ' + cWhere + ' LIMIT 1', q)) then begin
if (not q.EoF) then begin
cUid := q.A2UID();
end;
end;
DB_Close(q);

if (not Empty(cUid)) then begin
// ändern: qSqlInit + sys_uid
end else begin
// anlegen: qSqlInit ohne sys_uid
end;
</syntaxhighlight>

===Mehrere Felder sind EIN Schreibvorgang===

Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> entgegen
und schreibt sie mit '''einem''' <code>SaveData</code>. Fallen an derselben
Zeile mehrere Felder an, gehören sie in dasselbe Objekt:

<syntaxhighlight lang="pascal" line>
// FALSCH: fünf Felder, fünf Schreibvorgänge - und jeder Setzer, der sich
// seine sys_uid selbst holt, bringt zusätzlich eine eigene Abfrage mit
FeldSetzen(cUid, 'ti_status' , '9');
FeldSetzen(cUid, 'ti_grund' , cGrund);
FeldSetzen(cUid, 'ti_von' , cBenutzer);

// RICHTIG: ein Schreibobjekt, ein SaveData
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cUid);
q.qSet('ti_status', '9');
q.qSet('ti_grund' , cGrund);
q.qSet('ti_von' , cBenutzer);
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln
end;
qSqlFree(q);
</syntaxhighlight>

Das ist nicht nur eine Frage der Geschwindigkeit: einzeln geschriebene Felder
sind '''nicht atomar'''. Bricht der dritte Schreibvorgang ab, steht die Zeile
halb geändert da - Grund gesetzt, Zeitpunkt nicht.

Wird nichts gesetzt, darf auch nicht geschrieben werden: das Schreibobjekt dann
mit <code>qSqlFree</code> freigeben, statt ein leeres <code>SaveData</code>
abzusetzen.

{{Hinweis|Ein Setzer für '''ein''' Feld (<code>FeldSetzen(cUid, cFeld, cWert)</code>)
ist bequem und deshalb verführerisch. Er versteckt aber je Aufruf eine eigene
Abfrage und ein eigenes <code>SaveData</code>. Für einen Vorgang mit mehreren
Feldern gehört ein '''Editier-Helfer''' her, der das Schreibobjekt liefert -
geschrieben wird einmal am Ende.}}

===Keine Abfrage je Zeile===

Was in einer Liste je Zeile nachgeschlagen wird, kostet '''N''' Abfragen für
'''eine''' Antwort. Bei fünfzig Aufträgen sind das fünfzig Abfragen für ein
einziges Feld. Der Ausweg ist immer derselbe:

* Werte aus einer 1:1-Beziehung über einen <code>LEFT JOIN</code> mitnehmen - bei einem '''eindeutigen''' Index auf dem Join-Feld kann er die Zeilen nicht vervielfachen.
* Einzelwerte aus einer 1:n-Beziehung über eine '''Unterabfrage''' in der SELECT-Liste holen, nicht über einen Join (der Join würde die Zeilen vervielfachen).
* Eine echte Unterliste (Positionen, Dateien) nur dann nachladen, wenn ein '''Zählfeld''' in der Hauptabfrage sagt, dass es überhaupt eine gibt.

{{Hinweis|Ein GET soll '''lesen'''. Schreibvorgänge im Lesepfad - etwas
"beim ersten Ausliefern festschreiben" - vervielfachen sich mit der Zeilenzahl
und treffen den Aufrufer, der nur eine Liste angefordert hat.}}

===Schreibfehler erkennen===

'''<code>SaveData</code> liefert einen Boolean - und der ist die einzige
Fehlermeldung, die es gibt.''' (Auch der '''Parameter''' ist ein Boolean:
''NEW_RECORD'' und ''UPDATE_RECORD'' sind Wahrheitswerte, keine Zahlen.) Schlägt das Schreiben in der Datenbank fehl
(''Duplicate entry'' auf einem eindeutigen Index, zu langer Wert, fehlende
Spalte), dann

* wird '''keine''' Exception ausgelöst,
* steht '''nichts''' in ''RESTSRV_PROTO'',
* läuft das Skript weiter und antwortet mit dem Erfolg, den es selbst formuliert.

Wer den Aufruf als Anweisung schreibt, baut damit einen stillen Datenverlust ein.
Weil in einem Endpunkt schnell ein Dutzend Schreibvorgänge zusammenkommen, gehört
die Prüfung in eine eigene kleine Prozedur - am besten in die gemeinsame Lib:

<syntaxhighlight lang="pascal" line>
procedure Speichern(q: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
begin
lOk := q.SaveData(lNeu);
qSqlFree(q); // auch im Fehlerfall freigeben
if (not lOk) then begin
raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
end;
end;

// Aufruf statt SaveData + qSqlFree:
q := qSqlInit(oDB, 'tickets');
q.qSet('ti_betreff', cBetreff);
Speichern(q, NEW_RECORD, 'Ticket');
</syntaxhighlight>

Die Exception fängt der Server: er schreibt ''Schreiben fehlgeschlagen: Ticket''
nach '''RESTSRV_PROTO''' und antwortet mit '''500'''. Liegt ein
''Idempotency-Key'' an, wird er dabei '''freigegeben''' - die Anfrage ist also
wiederholbar (siehe Abschnitt Idempotenz).

{{Hinweis|Ein fehlgeschlagenes Schreiben ist kein Fall, in dem ein Endpunkt
sinnvoll weiterlaufen kann: die Fachwirkung ist dann unvollständig. Wer trotzdem
weitermachen will - etwa weil mehrere unabhängige Sätze geschrieben werden -,
prüft den Rückgabewert und baut selbst eine Antwort. Ignorieren darf man ihn
nie.}}

Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.

==Gemeinsamen Code auslagern==

Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:

<pre>
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</pre>

{| class="wikitable"
! Attribut !! Bedeutung
|-
| '''T''' || Tabelle, aus der geladen wird
|-
| '''I''' || Spalte, über die gesucht wird
|-
| '''V''' || Wert, der in dieser Spalte stehen muss
|-
| '''F''' || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}

Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Compiler sieht danach den zusammengesetzten Text - eine Funktion aus der Lib lässt
sich also aufrufen wie eine im Skript selbst geschriebene.

===Bewährtes Muster: Lib als eigene Endpunkt-Zeile===

Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
RESTSRV_ENDPOINTS''' abzulegen:

# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
# Den Lib-Quelltext ins Skript-Feld dieser Zeile schreiben (F7).
# '''Keine Berechtigung''' in der Berechtigungs-Liste vergeben - das ist der Schutz: ohne Berechtigung beantwortet der Server einen Aufruf mit 403.
# In jedem nutzenden Endpunkt die Direktive oben einfügen.

Damit ist die Lib reiner Ablageort und von aussen nicht nutzbar. Eine Änderung
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
angefasst werden muss.

{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Funktion hinzu, genügt es nicht, nur das nutzende Skript zu aktualisieren. Eine
ältere Lib lädt fehlerfrei - der Compiler meldet dann ausschliesslich die neuen
Namen als ''Unknown name'', was leicht wie ein Fehler im Skript aussieht.}}

{{Hinweis|Auch hier greift der Endpunkt-Cache: eine Änderung an der Lib wird erst
nach Ablauf des TTL (bis zu 60 Sekunden) wirksam.}}

==Fallstricke im Skript==

Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:

{| class="wikitable"
! Stolperstein !! Richtig
|-
| ''DB_SOpen('Y00…', oDB, …)'' - der AD-UID-Parameter aus dem Delphi-Code || Im Skript '''ohne UID''': <code>DB_SOpen(oDB, cSql, q)</code>. Gleiches gilt für <code>qSqlInit(oDB, 'tab')</code> und <code>qSqlRead(oDB, 'tab', cWhere)</code> - jede dieser Funktionen beginnt mit ''oDB''
|-
| ''oBody.TryGetValue<T>(…)'' || Generics gibt es nicht - über ''GetValue'' lesen (siehe oBody)
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'|' + wert + '|'</code>) und mit ''Pos'' prüfen
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
|-
| <code>q.SaveData(…)</code> als Anweisung schreiben || ''SaveData'' liefert einen '''Boolean'''. Ein SQL-Fehler beim Schreiben wirft '''keine''' Exception und landet in '''keinem''' Protokoll - der Rückgabewert ist die einzige Meldung. Immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Je Feld ein eigener Setzer-Aufruf || Ein <code>qSqlInit</code>-Objekt, beliebig viele <code>qSet</code>, '''ein''' <code>SaveData</code>. Einzeln geschrieben kostet jedes Feld eine eigene Abfrage samt eigenem Write - und der Vorgang ist nicht mehr atomar, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Ein Wert je Zeile nachgeschlagen || In einer Liste sind das N Abfragen für eine Antwort. Über <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n) mitnehmen, siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]]
|-
| Ausgabeparameter vom Typ <code>var … : TDateTime</code> || Bringt die Skript-VM zum '''Absturz''' (Assertion in ''dwsStack.pas''), und zwar beim ersten '''Lesen''' des Werts - nicht schon beim Schreiben, die Ursache liegt also nicht dort, wo der Fehler auffällt. <code>var string</code>, <code>var Integer</code> und <code>var Double</code> laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und erst beim Aufrufer wandeln
|}

==Skript-Cache==

Der Server cached das kompilierte Skript pro Endpunkt (Schlüssel: ''sys_date'' des Endpunkts). Zusätzlich werden die Endpunkt-Definitionen pro Server-Profil in einem TTL-Cache (Standard 60 s) gehalten. Eine Skript-Änderung über F7 wird daher erst nach Ablauf dieses TTL (bzw. nach einer Cache-Invalidierung) wirksam - typischerweise innerhalb einer Minute, nicht zwingend sofort.

==Verfügbare Bibliotheken==

Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:

* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
* ''Base.qSqlReg'' - Schreibzugriffe
* ''System.JSON'' - JSON-Objekte und -Arrays
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''

Die wichtigsten Aufrufe mit ihren Skript-Signaturen:

{| class="wikitable"
! Zweck !! Aufruf
|-
| Lesen || <code>DB_SOpen(oDB, cSql, q)</code>, dann <code>q.EoF</code>, <code>q.Next()</code>, <code>q.A2C('feld')</code> / <code>A2I</code> / <code>A2F</code> / <code>A2D</code> / <code>A2UID()</code>, am Ende <code>DB_Close(q)</code>
|-
| Neu anlegen || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('feld', wert)</code>, <code>if (not q.SaveData(NEW_RECORD)) then …</code>, <code>qSqlFree(q)</code> – der Rückgabewert ist Pflicht, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Ändern || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('sys_uid', cUid)</code>, <code>q.qSet(…)</code>, <code>if (not q.SaveData(UPDATE_RECORD)) then …</code>, <code>qSqlFree(q)</code> – '''nicht''' <code>qSqlRead</code>, siehe [[#Ändern: qSqlInit statt qSqlRead|Ändern]]. Alle Felder derselben Zeile in '''ein''' Objekt, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
|-
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
|}

{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
Skript nicht übersetzen.}}

Konkrete Beispiele:

* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-08-31T05:04:01Z

Rademacker:

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

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

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# 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 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.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|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 [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Die früheren Felder '''Sub-URL''' und '''Version''' werden nicht mehr ausgewertet. Eine Versionskennung wird ggf. als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''). Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|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/[Pfad-Template]

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.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen bleiben absichtlich stehen und werden ab 24 Stunden im Protokoll gemeldet - sie sind ein Support-Fall, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==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''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* 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.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf gibt den Eintrag nach 24 Stunden von selbst frei; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Beispiel6

2026-08-31T05:03:41Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 6: Datei-Upload und Ablage=

Dieses Beispiel zeigt einen Endpunkt, der '''Dateien entgegennimmt''': Ein
Aussendienst-Mitarbeiter fotografiert vor Ort ein Gerät, die App lädt das Foto zum
Auftrag hoch, der Server legt es ab und verknüpft es mit dem Vorgang.

Der Ablauf ist derselbe für Belege aus einem Scanner, Unterschriften-Bilder oder
Prüfprotokolle als PDF. Behandelt werden beide Übertragungsarten - der einfache
Upload für kleine Dateien und der fortsetzbare Upload für grosse.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App'', API-Key zufällig generiert, JWT aktiv
* '''Endpunkt:''' ''/orders/{uid}/photos'', Profil ''Public-API''
** '''Datei-Upload''' auf '''Ja''' setzen (<code>re_upload = 1</code>)
** '''Max. Upload-Grösse''' auf ''20'' (MB) setzen
* '''Berechtigung:''' Zugang ''Mobile-App'' für den Endpunkt freischalten

{{Hinweis|Ohne den Haken '''Datei-Upload''' lehnt der Server jeden Upload mit
'''415''' ab und das Skript läuft gar nicht erst an. Das ist die häufigste Ursache,
wenn ein Upload "ohne erkennbaren Grund" scheitert.}}

==Was der Server erledigt, bevor das Skript läuft==

Der Server nimmt die Datei entgegen, prüft die Grösse, legt sie in einem temporären
Verzeichnis ab und übergibt dem Skript drei Parameter:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_UPLOAD_PATH || Vollständiger Pfad zur temporären Datei
|-
| _OBS_UPLOAD_NAME || Originaldateiname, wie ihn der Client gesendet hat
|-
| _OBS_UPLOAD_CONTENTTYPE || Content-Type der Datei
|-
| _OBS_UPLOAD_SHA256 || SHA-256 der gespeicherten Datei (hex, klein)
|}

Zwei Dinge sind beim Schreiben des Skripts wichtig:

* '''<code>oBody</code> ist bei Uploads immer <code>nil</code>.''' Der Request-Body ist die Datei, kein JSON. Zusatzangaben (Kategorie, Bemerkung) kommen deshalb als '''Query-Parameter''' mit - oder, bei <code>multipart/form-data</code>, als weitere '''Formularfelder'''; die stehen dem Skript als <code>_OBS_FORM_<name></code> zur Verfügung.
* '''Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt.''' Der Server räumt sie nicht selbst weg.

==Endpunkt-Skript ''/orders/{uid}/photos''==

Das Skript prüft den Dateityp, baut einen Zielpfad aus Auftrag und Zeitstempel,
verschiebt die Datei dorthin und schreibt einen Verweis in die Datenbank.

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
const ZIEL_BASIS = 'D:\OBS\Daten\Auftragsfotos\';
var oRes, oErr, oHdr: TJSONObject;
cUid : string;
cTmpPfad : string;
cOrigName: string;
cTyp : string;
cEndung : string;
cKategorie: string;
cZielDir : string;
cZielName: string;
cZielPfad: string;
qNeu : TqSQL;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];
cTmpPfad := oParams.Values['_OBS_UPLOAD_PATH'];
cOrigName := oParams.Values['_OBS_UPLOAD_NAME'];
cTyp := oParams.Values['_OBS_UPLOAD_CONTENTTYPE'];
cKategorie := oParams.Values['kategorie']; // Query-Parameter, nicht Body

// 1) Gehoert der Auftrag zum Mandanten aus dem Token?
if (not AuftragGehoertZuMandant(oParams.Values['_OBS_JWT_CLAIM_tenant'], cUid)) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'NOT_FOUND');
oErr.AddPair('message', 'Auftrag nicht gefunden');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 404);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 2) Dateityp gegen eine Whitelist pruefen - niemals gegen eine
// Blacklist, und niemals dem Content-Type allein vertrauen.
cEndung := Lower(ExtractFileExt(cOrigName));
if ((cEndung <> '.jpg') and (cEndung <> '.jpeg') and (cEndung <> '.png') and (cEndung <> '.pdf')) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'Nur JPG, PNG und PDF sind zulässig');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 3) Zielname selbst bilden. Den Originalnamen NICHT als Pfad
// verwenden - er kommt vom Client und kann '..\' enthalten.
cZielDir := ZIEL_BASIS + DToS(Date()) + '\' + cUid + '\';
cZielName := DToSF(Now()) + '_' + GlobalUID() + cEndung;
cZielPfad := cZielDir + cZielName;

MyForceDirectories(cZielDir);

if (not FMove(cTmpPfad, cZielPfad)) then begin
// Fehlgeschlagenes Verschieben ist ein Serverproblem -> 500.
// Der Idempotency-Key wird bei 5xx wieder freigegeben, der
// Client darf denselben Schluessel erneut senden.
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'INTERNAL_ERROR');
oErr.AddPair('message', 'Datei konnte nicht abgelegt werden');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 500);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 4) Verweis in der Datenbank ablegen
qNeu := qSqlInit(oDB, 'AUFTRAG_DOKUMENT');
qNeu.qSet('ad_auftrag' , cUid);
qNeu.qSet('ad_pfad' , cZielPfad);
qNeu.qSet('ad_dateiname', cOrigName);
qNeu.qSet('ad_typ' , cTyp);
qNeu.qSet('ad_kategorie', cKategorie);
qNeu.qSet('ad_datum' , Now());
qNeu.SaveData(NEW_RECORD);
qSqlFree(qNeu);

// 5) 201 mit Location auf die abgelegte Datei
oHdr := TJSONObject.Create();
oHdr.AddPair('Location', '/orders/' + cUid + '/photos/' + cZielName);

oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('dateiname', cZielName);
oRes.AddPair('groesse' , FSize(cZielPfad));
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|Soll die Datei statt in ein Verzeichnis in das '''OBS-Dokumenten-System'''
wandern, ersetzt der DMS-Aufruf die Schritte 3 bis 5. Welche Funktion dafür
zuständig ist, hängt vom eingesetzten Dokumenttyp ab - bitte mit dem OBS-Support
klären.}}

==Test mit curl==

Einfacher Upload einer Datei (''-F'' erzeugt ''multipart/form-data''):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-F "datei=@C:\Fotos\geraet.jpg" ^
"https://api.meinserver.de/orders/4711/photos?kategorie=VORHER"

Antwort:

HTTP/1.1 201 Created
Location: /orders/4711/photos/20260817091233_A1B2C3.jpg
X-Trace-Id: 20260817T091233123-00001A

{"dateiname":"20260817091233_A1B2C3.jpg","groesse":248113}

Ein Upload an einen Endpunkt '''ohne''' Upload-Freigabe:

HTTP/1.1 415 Unsupported Media Type

Eine Datei über der eingestellten Grenze:

HTTP/1.1 413 Payload Too Large

==Grosse Dateien: fortsetzbarer Upload==

Bei einem Foto aus dem Mobilfunknetz reisst die Verbindung schnell einmal ab. Für
solche Fälle überträgt der Client die Datei in Teilstücken und kann nach einem
Abbruch dort weitermachen, wo er aufgehört hat. '''Am Endpunkt-Skript ändert sich
dafür nichts''' - der Server sammelt die Teilstücke selbst ein und ruft das Skript
erst auf, wenn die Datei vollständig ist.

Der erste Teil trägt den Dateinamen (Base64-kodiert im Header
<code>Upload-Metadata</code>) und liefert eine <code>Upload-Id</code> zurück:

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Content-Range: bytes 0-1048575/5000000" ^
-H "Upload-Metadata: filename Z2VyYWV0LmpwZw==,filetype aW1hZ2UvanBlZw==" ^
--data-binary "@teil1.bin" ^
https://api.meinserver.de/orders/4711/photos

HTTP/1.1 308 Resume Incomplete
Upload-Id: 7f2a9c84...
Upload-Offset: 1048576
Range: bytes=0-1048575

Jeder weitere Teil sendet die ''Upload-Id'' mit. Der letzte Teil bekommt die
normale Antwort des Skripts (hier '''201'''). Nach einem Abbruch fragt der Client
den Stand ab und setzt dort auf:

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Content-Range: bytes */5000000" -H "Upload-Id: 7f2a9c84..." ^
https://api.meinserver.de/orders/4711/photos

HTTP/1.1 308 Resume Incomplete
Upload-Offset: 3145728

{{Hinweis|Der Zwischenstand liegt im Arbeitsspeicher des Dienstes. Wird der
REST-Dienst neu gestartet, muss ein unvollständiger Upload von vorn beginnen.}}

==Doppelte Uploads vermeiden==

Bricht die Verbindung ab, nachdem der Server die Datei schon abgelegt hat, würde ein
Wiederholversuch dasselbe Foto ein zweites Mal einliefern. Dagegen sendet der Client
den Header <code>Idempotency-Key</code> - für jedes Foto einen eigenen, über alle
Wiederholversuche hinweg denselben:

-H "Idempotency-Key: foto-4711-0003"

Der Server erkennt die Wiederholung und liefert die '''gespeicherte 201-Antwort'''
samt Header <code>Idempotent-Replay: true</code> zurück, ohne das Skript erneut zu
starten. Es entsteht also weder eine zweite Datei noch ein zweiter DB-Eintrag.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz.

==Was zeigt das Beispiel?==

* Endpunkt mit '''Datei-Upload-Freigabe''' (<code>re_upload</code>) und eigener Grössenbegrenzung.
* Zugriff auf die hochgeladene Datei über ''_OBS_UPLOAD_PATH'', ''_OBS_UPLOAD_NAME'' und ''_OBS_UPLOAD_CONTENTTYPE''.
* Zusatzangaben als '''Query-Parameter''', weil ''oBody'' bei Uploads ''nil'' ist.
* '''Whitelist''' für zulässige Dateitypen und ein '''selbst gebildeter Zielname''' - der Originalname landet nie im Pfad.
* Übernahme der temporären Datei mit ''FMove''; ohne diesen Schritt bleibt sie liegen.
* Antwort mit '''201''' und ''Location''-Header.
* Fortsetzbarer Upload ohne jede Änderung am Skript.
* Schutz gegen doppelte Einlieferung über den ''Idempotency-Key''.

==Siehe auch==

* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Upload-Parameter und Protokoll im Detail
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Freigabe, Grössenlimit, Idempotenz
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5]] - Schreibzugriff mit Statuscodes und ETag

OBS/Kostenpflichtige Module/RESTServer/Scripting

2026-08-31T05:03:18Z

Rademacker:

{{Kostenpflichtige Module}}

=Anleitung für Endpunkt-Skripte=

Jede Anfrage an einen Endpunkt wird nach erfolgreicher Authentifizierung und Autorisierung an das hinterlegte Skript weitergegeben. Das Skript ist in Object Pascal geschrieben und greift auf die OBS-Bibliothek (DB-Zugriff, Hilfsfunktionen) zu.

==Sicherheitshinweise==

{{Hinweis|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Übergabeparameter dürfen niemals ungeprüft in SQL-Anweisungen eingebaut werden. Werte immer über ''DB_SQLVal'' bzw. Parameter-Bindings absichern, Eingabewerte gegen Whitelists prüfen.}}

* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
* Nur das zurückgeben, was der Konsument wirklich braucht - keine internen IDs, keine Sys-Felder, keine Passwörter.
* Bei Fehlern keine internen Details an den Konsumenten zurückgeben; stattdessen schreibt der Server ohnehin Detail-Einträge in '''RESTSRV_PROTO'''.

==Methoden-Signatur==

Pro HTTP-Methode wird im Skript eine gleichnamige Funktion implementiert. Der Server ruft genau die Funktion auf, die zur Methode des eingehenden Requests passt.

function Get (oParams: TStrings; oBody: TJSONObject): string;
function Post (oParams: TStrings; oBody: TJSONObject): string;
function Put (oParams: TStrings; oBody: TJSONObject): string;
function Delete(oParams: TStrings; oBody: TJSONObject): string;
function Patch (oParams: TStrings; oBody: TJSONObject): string;

Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
Not Allowed''' (<code>METHOD_NOT_ALLOWED</code>) und nennt im Header
<code>Allow</code> die Verben, die dieses Skript tatsächlich anbietet - die Liste
stammt aus dem kompilierten Skript und kann deshalb nicht veralten:

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT

Ein im Vertrag zugesagtes Verb braucht also seine Funktion. Fehlt sie, ist das an
der Antwort sofort zu erkennen und '''kein''' Serverfehler.

==Parameter==

===oParams (TStrings)===

Enthält alle Query-Parameter, POST-Parameter (form-urlencoded) sowie die durchgereichten HTTP-Header. Werte sind immer Strings.

Filterung durch den Server:

* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
* Parameter mit Präfix '''_OBS_''' können von aussen nicht gesetzt werden; sie sind für interne Werte reserviert.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.

Zugriff im Skript:

if (not Empty(oParams.Values['kundennr'])) then begin
cKundenNr := oParams.Values['kundennr'];
end;

===oBody (TJSONObject)===

Enthält den Request-Body, sofern dieser ein gültiges JSON-Objekt ist. Bei leerem oder nicht-JSON-Body wird ''nil'' übergeben.

{{Hinweis|'''Generics funktionieren im Skript nicht.''' Aus Delphi bekannte
Schreibweisen wie ''oBody.TryGetValue<string>('feld', cVar)'' lassen sich nicht
übersetzen. Gelesen wird über ''GetValue''.}}

''GetValue'' liefert ''nil'', wenn das Feld im Body '''nicht enthalten''' ist -
daran lässt sich „nicht gesendet" von „leer gesendet" unterscheiden. Der Wert ist
immer ein '''String''' und wird bei Bedarf selbst gewandelt.

cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username');
if (Assigned(oVal)) then begin
cUser := oVal.Value;
end;
oVal := oBody.GetValue('password');
if (Assigned(oVal)) then begin
cPass := oVal.Value;
end;
end;

Bei mehr als zwei Feldern lohnt eine kleine Hilfsfunktion, die das Muster einmal
kapselt:

<syntaxhighlight lang="pascal" line>
function _BodyStr(oBody: TJSONObject; const cFeld: string): string;
var oVal: TJSONValue;
begin
result := '';
if (oBody = nil) then begin
exit;
end;
oVal := oBody.GetValue(cFeld);
if (Assigned(oVal)) then begin
result := oVal.Value;
end;
end;

// Aufruf:
cBetreff := _BodyStr(oBody, 'betreff');
</syntaxhighlight>

Andere Typen entstehen aus dem String:

{| class="wikitable"
! Zieltyp !! Umwandlung
|-
| Ganzzahl || <code>iVal(_BodyStr(oBody, 'menge'))</code>
|-
| Kommazahl || <code>fVal(StrTran(_BodyStr(oBody, 'preis'), '.', ','))</code> - '''JSON liefert den Dezimalpunkt''', ''fVal'' erwartet die lokale Notation
|-
| Boolean || <code>Lower(_BodyStr(oBody, 'aktiv')) = 'true'</code>
|-
| Datum/Zeit || ISO-8601-String selbst zerlegen (''CToDT'' erwartet das deutsche Format)
|}

Maximale Body-Grösse: 10 MB.

===Reservierte _OBS_-Parameter===

Bei aktiver JWT-Authentifizierung stehen die Token-Claims als Parameter zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_JWT_ID || JWT-Id (''jti''-Claim) - typisch die User-Id. '''Muss nicht eindeutig sein''': die Sitzung führt der Server über eigene Kennungen (siehe unten)
|-
| _OBS_JWT_SUBJECT || Subject (''sub''-Claim) - typisch Benutzername
|-
| _OBS_JWT_AUDIENCE || Audience (''aud''-Claim) - typisch Mandant / Rolle
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim des Tokens (z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles); im Folge-Skript lesbar
|-
| _OBS_TRACE_ID || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}

Unabhängig von JWT stehen ausserdem immer zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_SERVER_TIME || Aktuelle Serverzeit als ISO-8601 '''mit UTC-Offset''' (z.B. ''2026-08-17T09:12:33+02:00''). Nützlich, um Datumswerte in derselben Zeitzone auszuliefern, in der der Server arbeitet, und damit ein Client seinen Uhren-Versatz bestimmen kann
|-
| _OBS_JWT_EXP_SEC || Laufzeit des Access-Tokens in Sekunden (''JWT-Exp'' × 60). Damit kann ein Konfigurations-Endpunkt denselben Wert ausliefern, den der Token wirklich hat
|}

Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.

Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
''_OBS_JWT_CLAIM_sid'' und ''_OBS_JWT_CLAIM_rid'':

{| class="wikitable"
! Claim !! Inhalt
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
|}

Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Skripts gesetzt - ein Skript kann sie also auch mit ''_OBS_JWT_CLAIM_sid'' nicht
überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.

===Pfad-Parameter===

Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte als reservierte Parameter mit Präfix '''_OBS_PATH_''' in ''oParams'' bereit:

{| class="wikitable"
! Template !! Zugriff im Skript
|-
| <code>/orders/{uid}</code> || ''oParams.Values['_OBS_PATH_uid']''
|-
| <code>/orders/{uid}/modules/{code}</code> || ''oParams.Values['_OBS_PATH_uid']'', ''oParams.Values['_OBS_PATH_code']''
|}

Da der Präfix ''_OBS_'' für von aussen gelieferte Header- und Query-Parameter gesperrt ist, sind diese Werte nicht durch den Client fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].

===Datei-Uploads===

Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), nimmt der Server
hochgeladene Dateien entgegen, legt sie in einem temporären Verzeichnis ab und
übergibt dem Skript Pfad, Originalname und Content-Type über reservierte
Parameter. Das Skript entscheidet selbst über die weitere Verarbeitung (z.B.
DMS-Ablage). Der Body wird in diesem Fall '''nicht''' als JSON geparst - ''oBody''
ist ''nil''. Es gilt nicht das JSON-Body-Limit (10 MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25 MB;
Überschreitung -> 413).

Beide Übertragungsarten - <code>multipart/form-data</code> und der resumable
<code>Content-Range</code>-Upload - liefern dem Skript dieselben Parameter:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_UPLOAD_PATH || Vollständiger Pfad zur temporären Datei auf dem Server
|-
| _OBS_UPLOAD_NAME || Originaldateiname
|-
| _OBS_UPLOAD_CONTENTTYPE || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt)
|-
| _OBS_UPLOAD_SHA256 || SHA-256 der '''gespeicherten''' Datei, hex in Kleinbuchstaben. Damit lässt sich eine vom Client mitgesendete Prüfsumme vergleichen - erst dieser Vergleich macht aus ihr eine Zusicherung
|}

Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''_OBS_UPLOAD_PATH'' und ''_OBS_UPLOAD_NAME''
gesetzt sind, sobald es läuft.

{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}

====Einfacher Upload (multipart/form-data)====

Eine Datei pro Request. Name und Content-Type stammen aus der
<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
Server speichert die erste Datei-Partie und ruft das Skript auf.

Die '''übrigen Partien''' des Formulars - alles ohne <code>filename=</code> -
übergibt der Server als <code>_OBS_FORM_<name></code>. Der Wert ist UTF-8 und
auf 1024 Zeichen begrenzt, der Name auf Buchstaben, Ziffern und Unterstrich
reduziert. Zusatzangaben lassen sich damit im selben Request mitschicken, ohne sie
an die URL zu hängen:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cPfad: string;
cName: string;
cTyp : string;
begin
oRes := TJSONObject.Create();
try
cPfad := oParams.Values['_OBS_UPLOAD_PATH'];
cName := oParams.Values['_OBS_UPLOAD_NAME'];
cTyp := oParams.Values['_OBS_UPLOAD_CONTENTTYPE'];

// ... Datei aus cPfad ins DMS / Zielverzeichnis uebernehmen ...

oRes.AddPair('status' , 'ok');
oRes.AddPair('dateiname', cName);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

====Resumable/Chunked Upload (Content-Range)====

Für grosse Dateien überträgt der Client die Datei in Teilstücken (Chunks) mit dem
Header <code>Content-Range: bytes START-END/TOTAL</code>. Der Server hängt die
Chunks '''sequentiell''' an eine Session-Datei an und behandelt unvollständige
Uploads selbst - das Endpunkt-Skript läuft '''erst beim vollständigen Upload'''
(dann mit gesetztem ''_OBS_UPLOAD_PATH'', ''_OBS_UPLOAD_NAME'' und
''_OBS_UPLOAD_CONTENTTYPE'').

Name und Content-Type sind im <code>Content-Range</code>-Protokoll nicht enthalten;
der Client liefert sie deshalb '''im ersten Chunk''' über den Header
<code>Upload-Metadata</code> (Format wie bei tus: kommagetrennte Paare
<code>schlüssel base64wert</code>, Werte Base64-kodiert):

<pre>
Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm
</pre>

Erkannt werden die Schlüssel <code>filename</code> (Pflicht) und
<code>filetype</code> (optional). Fehlt <code>filename</code> im ersten Chunk,
wird der Upload mit '''400''' abgelehnt, ohne dass eine Datei angelegt wird.
Folge-Chunks und Statusabfragen müssen die Metadaten nicht erneut senden.

Ablauf (vom Client gesteuert, der Server antwortet jeweils):

{| class="wikitable"
! Request !! Server-Antwort
|-
| Erster Chunk <code>Content-Range: bytes 0-1048575/5000000</code> + <code>Upload-Metadata</code> || '''308''' Resume Incomplete + Header <code>Upload-Id</code>, <code>Upload-Offset</code>, <code>Range</code>
|-
| weitere Chunks (jeweils <code>Upload-Id</code> mitsenden) || '''308''' mit aktualisiertem <code>Upload-Offset</code>
|-
| letzter Chunk (Bereich erreicht TOTAL) || normale Skript-Antwort (z.B. '''200'''/'''201''')
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> || aktueller <code>Upload-Offset</code>, ohne anzuhängen (Resume)
|}

{| class="wikitable"
! Header !! Richtung !! Bedeutung
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
|-
| Upload-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
|-
| Upload-Id || Request/Response || Session-Kennung. Fehlt sie im ersten Request, erzeugt der Server eine und gibt sie zurück; alle Folge-Chunks müssen sie mitsenden.
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
|}

Der Server hängt einen Chunk '''nur an, wenn START dem bereits gespeicherten Stand
entspricht'''. Bei Abweichung (doppelter Chunk, Lücke) wird nicht angehängt,
sondern der aktuelle ''Upload-Offset'' zurückgemeldet - der Client setzt ab dort
neu auf. Eine separate Statusabfrage ist für ein Resume daher nicht zwingend nötig.

Überschreitet ein Chunk bzw. die Gesamtgrösse das Limit (''re_upload_size''),
antwortet der Server mit '''413 Payload Too Large'''.

{{Hinweis|Der Upload-Status liegt prozesslokal im Speicher. Nach einem Neustart des Servers muss ein unvollständiger Upload neu begonnen werden.}}

==Rückgabe==

Die Rückgabe ist immer ein '''JSON-String'''. Wird ein leerer String zurückgegeben, antwortet der Server automatisch mit ''{}''. Der Server setzt Content-Type auf ''application/json; charset=utf-8'' und Status auf 200, sofern das Skript nicht selbst einen Fehler signalisiert.

Einfaches Beispiel:

<syntaxhighlight lang="pascal" line>
function Get(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
oRes := TJSONObject.Create();
try
oRes.AddPair('wert_string', '123');
oRes.AddPair('wert_int' , 456);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Antwort steuern: Statuscode, Header, traceId==

Ein Skript kann den HTTP-Statuscode und beliebige Response-Header über reservierte Felder in der Antwort setzen. Der Server wertet sie aus und entfernt sie vor dem Senden aus dem Body.

{| class="wikitable"
! Antwort-Feld !! Wirkung
|-
| _OBS_HTTP_STATUS (Zahl) || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200. Bei 204 wird kein Body gesendet.
|-
| _OBS_HEADERS (Objekt) || Beliebige Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen/Werten werden entfernt (Schutz vor Header-Injection).
|-
| _OBS_JWT_REVOKE (Text) || Sperrt die Sitzung des vorgelegten Tokens (''session'') oder alle Sitzungen des Subjects (''all''). Damit wird ein Endpunkt zum Logout, ohne eigene Verwaltung. Scheitert das Sperren, antwortet der Server mit '''503''' statt mit der Antwort des Skripts - siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Abschnitt Abmelden.
|}

Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oParams.Values['_OBS_TRACE_ID']'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

===Beispiel: Anlegen mit 201, Location und ETag===

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
// ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...
oHdr := TJSONObject.Create();
oHdr.AddPair('Location', '/v1/orders/' + cNeueUid);
oHdr.AddPair('ETag', '1');

oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('uid', cNeueUid);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Beispiel: Strukturierter Fehler mit Statuscode und traceId===

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
oErr := TJSONObject.Create();
oErr.AddPair('code', 'VALIDATION_FAILED');
oErr.AddPair('message', 'Feld "menge" fehlt');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Beispiel: Optimistic Concurrency (ETag / If-Match)===

Mit Statuscode, Headern und dem lesbaren Header ''If-Match'' führt das Skript je Datensatz einen Versionszähler und lehnt veraltete Schreibzugriffe mit 409 ab:

<syntaxhighlight lang="pascal" line>
function Put(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
nAktuell, nIfMatch: integer;
begin
oRes := TJSONObject.Create();
try
nAktuell := AuftragVersion(oParams.Values['_OBS_PATH_uid']);
nIfMatch := iVal(oParams.Values['if-match']);

if (nIfMatch <> nAktuell) then begin
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell));
oRes.AddPair('_OBS_HTTP_STATUS', 409);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'VERSION_CONFLICT'));
result := oRes.ToJSON();
exit;
end;

// ... speichern, Version hochzählen ...
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell + 1));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Idempotenz - was das Skript beachten muss==

Sendet ein Konsument bei ''POST''/''PUT''/''PATCH''/''DELETE'' den Header
<code>Idempotency-Key</code>, fängt der '''Server''' doppelte Sendungen ab. Das
Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine
Prüfung am Anfang der Methode.

Was das Skript wissen muss:

{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
|-
| '''2xx''' || Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
|-
| '''5xx''' oder Exception || Der Schlüssel bleibt belegt, der Fall wird protokolliert. Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist
|}

Daraus folgen zwei Regeln für Endpunkt-Skripte:

* '''Fachliche Ablehnungen als 4xx melden''' (422, 409, 404), nicht als 2xx mit Fehlertext im Body. Sonst wird die Ablehnung gespeichert und der Konsument bekommt sie bei jedem weiteren Versuch erneut - auch nachdem er den Fehler behoben hat.
* '''Die Antwort muss vollständig sein.''' Was zurückgegeben wird, wird eingefroren. Ein Feld, das erst der zweite Aufruf ergänzen würde, kommt beim Konsumenten nie an.

{{Hinweis|Vor dieser Server-Funktion mussten Skripte die Idempotenz selbst
abbilden. Solche Skripte laufen unverändert weiter - die Doppelprüfung schadet
nicht, ist aber überflüssig und kann beim nächsten Überarbeiten entfallen.}}

Der vollständige Ablauf und die Statuscodes stehen unter
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==JWT-Authentifizierungs-Skript==

Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser : string;
cPass : string;
begin
oRes := TJSONObject.Create();
try
// Eingangsdaten lesen (Body oder Query-Param)
cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username');
if (Assigned(oVal)) then begin
cUser := oVal.Value;
end;
oVal := oBody.GetValue('password');
if (Assigned(oVal)) then begin
cPass := oVal.Value;
end;
end;

// Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
if (PasswortPasst(cUser, cPass)) then begin
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT', cUser);
oRes.AddPair('_OBS_JWT_AUDIENCE', 'mandant1');
end else begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Login fehlgeschlagen');
end;

result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

Rückgabewerte:

{| class="wikitable"
! status !! Bedeutung
|-
| 1 || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
|-
| 9 || Misserfolg, der Server antwortet mit '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
|}

{{Hinweis|Der Text aus ''error'' geht bei ''status'' = 9 '''an den Konsumenten'''
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Endanwender verständlich sein und keine internen Details verraten.}}

Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
„Passwort falsch" erscheinen.

Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.

===Aufbau der Token-Antwort===

Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
Feldern, die das Skript zurückgibt''':

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...",
"accessToken": "eyJ...",
"refreshToken":"eyJ...",
"expiresIn": 28800,
"serverTime": "2026-08-17T09:12:33+02:00"}

{| class="wikitable"
! Feld !! Herkunft
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
|-
| serverTime || Serverzeit ISO-8601 mit Offset
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
|}

Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.

===Custom-Claims, serverTime und Refresh===

Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:

{| class="wikitable"
! RÜckgabefeld !! Bedeutung
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als oParams.Values['_OBS_JWT_CLAIM_<name>'].
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
|}

Jedes Token trägt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh'') sowie die Sitzungskennungen ''sid'' und ''rid'' des Servers. Die Antwort enthält bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusätzlich ''refreshToken'':

{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}

{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''_OBS_JWT_CLAIM_*''), nie aus Body oder Query.}}

====Refresh-Methode====

Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
(Signatur, Ablauf, ''token_use=refresh'') und in der Sitzung '''entwertet'''.
Einmalgebrauch, Rotation und Sperrliste sind damit Sache des Servers. Das Skript
liefert nur noch die aktuellen Claims - genau das ist der Sinn des Aufrufs: eine
zwischenzeitlich geänderte Rolle oder ein gewechselter Mandant wirken spätestens
mit der nächsten Erneuerung.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal - einmal im Skript, einmal im
Server - und riskiert, dass beide Seiten unterschiedlicher Meinung sind. Der
Server sieht die Skript-Tabelle nicht, und das Skript sieht die Sitzung nicht.}}

Ein bereits benutztes Refresh-Token wird mit '''401''' abgelehnt. Erfolgt die
erneute Vorlage innerhalb von 60 Sekunden, bleibt die Sitzung bestehen (paralleler
Refresh einer App); danach gilt sie als Wiedervorlage und die '''gesamte Sitzung
wird gesperrt'''. Details in [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

Das alte Refresh-jti steht weiterhin als ''oParams.Values['_OBS_JWT_ID']'' bereit,
falls das Skript es für eigene Protokollierung braucht.

<syntaxhighlight lang="pascal" line>
function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cUser: string;
begin
oRes := TJSONObject.Create();
try
cUser := oParams.Values['_OBS_JWT_SUBJECT'];

// Der Server hat das vorgelegte Refresh-Token bereits geprueft und
// entwertet. Hier wird nur entschieden, ob der Benutzer die Sitzung
// fortsetzen darf - und mit welchen Rechten.
if (not BenutzerAktiv(cUser)) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
result := oRes.ToJSON();
exit;
end;

// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das neue Refresh-Token aus
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Abmelden (Logout)===

'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Phase 4.

Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
'''gewöhnlichen Endpunkt''' und setzt dort ''_OBS_JWT_REVOKE''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
oRes := TJSONObject.Create();
try
GeraeteRegistrierungLoeschen(oParams.Values['_OBS_JWT_SUBJECT']);

// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
oRes.AddPair('_OBS_JWT_REVOKE' , 'session');
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
abgemeldet, während sein Token weiterläuft.

==Fehlerbehandlung im Skript==

Tritt im Skript eine Exception auf oder schlägt die Syntax-Prüfung fehl, antwortet der Server mit 500 ''Interner Fehler'' und protokolliert die Detail-Meldung in '''RESTSRV_PROTO''' (mit Skript-Fehlertext). Der Konsument sieht keine internen Details.

Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Will das Skript einen spezifischen Fehler an den Konsumenten zurückgeben, sollte es
'''dasselbe Format und einen passenden Statuscode''' verwenden:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
if (Empty(oParams.Values['kundennr'])) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'Parameter ''kundennr'' fehlt');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;
// ...
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
Body auszuwerten - und nur so gibt der Server einen belegten
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}

Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.

==Gemeinsamen Code auslagern==

Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:

<pre>
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</pre>

{| class="wikitable"
! Attribut !! Bedeutung
|-
| '''T''' || Tabelle, aus der geladen wird
|-
| '''I''' || Spalte, über die gesucht wird
|-
| '''V''' || Wert, der in dieser Spalte stehen muss
|-
| '''F''' || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}

Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Compiler sieht danach den zusammengesetzten Text - eine Funktion aus der Lib lässt
sich also aufrufen wie eine im Skript selbst geschriebene.

===Bewährtes Muster: Lib als eigene Endpunkt-Zeile===

Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
RESTSRV_ENDPOINTS''' abzulegen:

# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
# Den Lib-Quelltext ins Skript-Feld dieser Zeile schreiben (F7).
# '''Keine Berechtigung''' in der Berechtigungs-Liste vergeben - das ist der Schutz: ohne Berechtigung beantwortet der Server einen Aufruf mit 403.
# In jedem nutzenden Endpunkt die Direktive oben einfügen.

Damit ist die Lib reiner Ablageort und von aussen nicht nutzbar. Eine Änderung
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
angefasst werden muss.

{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Funktion hinzu, genügt es nicht, nur das nutzende Skript zu aktualisieren. Eine
ältere Lib lädt fehlerfrei - der Compiler meldet dann ausschliesslich die neuen
Namen als ''Unknown name'', was leicht wie ein Fehler im Skript aussieht.}}

{{Hinweis|Auch hier greift der Endpunkt-Cache: eine Änderung an der Lib wird erst
nach Ablauf des TTL (bis zu 60 Sekunden) wirksam.}}

==Fallstricke im Skript==

Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:

{| class="wikitable"
! Stolperstein !! Richtig
|-
| ''DB_SOpen('Y00…', oDB, …)'' - der AD-UID-Parameter aus dem Delphi-Code || Im Skript '''ohne UID''': <code>DB_SOpen(oDB, cSql, q)</code>. Gleiches gilt für <code>qSqlInit(oDB, 'tab')</code> und <code>qSqlRead(oDB, 'tab', cWhere)</code> - jede dieser Funktionen beginnt mit ''oDB''
|-
| ''oBody.TryGetValue<T>(…)'' || Generics gibt es nicht - über ''GetValue'' lesen (siehe oBody)
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'|' + wert + '|'</code>) und mit ''Pos'' prüfen
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
|}

==Skript-Cache==

Der Server cached das kompilierte Skript pro Endpunkt (Schlüssel: ''sys_date'' des Endpunkts). Zusätzlich werden die Endpunkt-Definitionen pro Server-Profil in einem TTL-Cache (Standard 60 s) gehalten. Eine Skript-Änderung über F7 wird daher erst nach Ablauf dieses TTL (bzw. nach einer Cache-Invalidierung) wirksam - typischerweise innerhalb einer Minute, nicht zwingend sofort.

==Verfügbare Bibliotheken==

Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:

* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
* ''Base.qSqlReg'' - Schreibzugriffe
* ''System.JSON'' - JSON-Objekte und -Arrays
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''

Die wichtigsten Aufrufe mit ihren Skript-Signaturen:

{| class="wikitable"
! Zweck !! Aufruf
|-
| Lesen || <code>DB_SOpen(oDB, cSql, q)</code>, dann <code>q.EoF</code>, <code>q.Next()</code>, <code>q.A2C('feld')</code> / <code>A2I</code> / <code>A2F</code> / <code>A2D</code> / <code>A2UID()</code>, am Ende <code>DB_Close(q)</code>
|-
| Neu anlegen || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('feld', wert)</code>, <code>q.SaveData(NEW_RECORD)</code>, <code>qSqlFree(q)</code>
|-
| Ändern || <code>q := qSqlRead(oDB, 'tab', cWhere)</code>, <code>q.qSet(…)</code>, <code>q.SaveData(UPDATE_RECORD)</code>, <code>qSqlFree(q)</code>
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
|-
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
|}

{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
Skript nicht übersetzen.}}

Konkrete Beispiele:

* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

OBS/Kostenpflichtige Module/RESTServer/Endpunkte

2026-08-31T05:03:04Z

Rademacker:

{{Kostenpflichtige Module}}

= Endpunkte =

Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
realisiert und ist genau einem Server-Profil zugeordnet.

== Routing über Pfad-Templates ==

Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
'''Platzhalter''' enthalten:

* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
* '''Platzhalter''' in geschweiften Klammern – z. B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.

Beispiele für gültige Templates:

{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}

=== Präzedenz bei mehreren Treffern ===

Passen mehrere Templates auf denselben Pfad, '''gewinnt das spezifischste''' –
also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code>
das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf
<code>/orders/{uid}</code> matcht.

== Hauptfelder eines Endpunkts ==

{| class="wikitable"
! Feld !! Spalte !! Zweck
|-
| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code>
|-
| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
|-
| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
|-
| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
|-
| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
|-
| '''Info''' || – || Dokumentations-Freitext
|-
| '''Datei-Upload''' || <code>re_upload</code> || Erlaubt Datei-Uploads an diesem Endpunkt (<code>0</code> = aus, <code>1</code> = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
|-
| '''Max. Upload-Grösse''' || <code>re_upload_size</code> || Maximale Dateigrösse in MB. Leer/0 = Standard 25 MB. Überschreitung wird mit 413 abgelehnt.
|}

== Pfad-Parameter im Skript ==

Die aus den Platzhaltern erfassten Werte stehen im Endpunkt-Skript als
reservierte Parameter mit Präfix <code>_OBS_PATH_</code> zur Verfügung:

<syntaxhighlight lang="pascal">
function Get(oParams: TStrings; oBody: TJSONObject): string;
var cUid: string;
begin
cUid := oParams.Values['_OBS_PATH_uid']; // aus /orders/{uid}
// ...
end;
</syntaxhighlight>

Da der Präfix <code>_OBS_</code> für von außen gelieferte Header/Query-Parameter
gesperrt ist, können diese Werte nicht durch den Client überschrieben werden.

== Datei-Uploads ==

Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.

Die maximal zulässige Dateigrösse wird pro Endpunkt über <code>re_upload_size</code>
(in MB) festgelegt; ohne Angabe gilt der Standard von '''25 MB'''. Wird das
Limit überschritten, antwortet der Server mit '''413 Payload Too Large'''. Für
Uploads gilt nicht das JSON-Body-Limit (10 MB), sondern dieses Endpunkt-Limit.
Der Originalname (beim resumable Upload über den Header <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit 413/400 abgelehnt. Dem Skript stehen Pfad, Name, Content-Type und die SHA-256-Prüfsumme der gespeicherten Datei als <code>_OBS_UPLOAD_*</code>-Parameter zur Verfügung; bei <code>multipart/form-data</code> zusätzlich die übrigen Formularfelder als <code>_OBS_FORM_*</code> (Details: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

Unterstützt werden zwei Übertragungsarten:

* '''Einfacher Upload''' per <code>multipart/form-data</code> (eine Datei pro Request).
* '''Resumable/Chunked Upload''' per <code>Content-Range</code> (grosse Dateien, fortsetzbar nach Abbruch).

Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und
übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage,
DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und
Beispiele: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== HTTP-Methode ==

Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
Pfad-Formen (z. B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
'''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.

== URL-Struktur ==

<pre>
http://[Host][:Port][Pfad-Template]
</pre>

Beispiele:
* <code>https://api.meinserver.de/orders</code>
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>

== Versionierung ==

Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z. B. <code>/orders/v1</code> oder
<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:

# Bestehenden Endpunkt unverändert lassen.
# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
# Berechtigungen für neue Konsumenten setzen.
# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.

== Zugriffskontrolle ==

Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
dürfen. Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
Zugriff '''pro Pfad-Form''' granular vergeben (z. B. Lesen von
<code>/orders/{uid}</code> erlauben, aber das ändernde
<code>PUT /orders/{uid}/modules/{code}</code> nicht).

== Caching ==

Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
(TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher
erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
zwingend sofort.

== HTTP-Fehlercodes ==

{| class="wikitable"
! Code !! Ursache
|-
| '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
|-
| '''403''' || Zugang fehlt in der Berechtigungsliste
|-
| '''401''' || API-Key ungültig/fehlend, JWT abgelaufen oder Sitzung gesperrt (''AUTH_EXPIRED'')
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
|-
| '''405''' || Das Endpunkt-Skript hat für die angefragte HTTP-Methode keine Funktion; der Header <code>Allow</code> nennt die vorhandenen
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>)
|-
| '''429''' || Rate-Limit überschritten; die Antwort enthält den Header <code>Retry-After</code>
|-
| '''503''' || Eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet; die Antwort enthält <code>Retry-After</code>
|-
| '''409''' || Ein früherer Aufruf mit demselben <code>Idempotency-Key</code> ist ohne Ergebnis geblieben (<code>IDEMPOTENCY_UNRESOLVED</code>)
|-
| '''422''' || Derselbe <code>Idempotency-Key</code> wurde mit '''anderem''' Inhalt gesendet (<code>IDEMPOTENCY_KEY_REUSED</code>)
|-
| '''400''' || Die Anfrage wurde unverschlüsselt an einen TLS-Port geschickt (<code>http</code> statt <code>https</code>). Die Abweisung erfolgt vor Authentifizierung und Endpunkt-Skript
|}

Jede Fehlerantwort besteht aus einem <code>error</code>-Objekt mit
maschinenlesbarem Code - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. <code>201</code>, <code>204</code>, <code>409</code>, <code>422</code>) sowie Response-Header wie <code>ETag</code> oder <code>Location</code> - siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Idempotenz ==

Schickt ein Konsument bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code>
oder <code>DELETE</code> den Header <code>Idempotency-Key</code>, sorgt der Server
selbst dafür, dass eine wiederholte Sendung '''keine Zweitwirkung''' hat. Das gilt
für '''jeden''' Endpunkt - es muss weder am Endpunkt etwas eingestellt noch im
Skript etwas programmiert werden.

{| class="wikitable"
! Situation !! Antwort des Servers
|-
| Erster Aufruf || Endpunkt läuft normal, das Ergebnis wird zum Schlüssel gespeichert
|-
| Wiederholung, gleicher Inhalt || '''Gespeicherte Antwort''' (gleicher Statuscode, gleicher Body, gleiche Header) plus Header <code>Idempotent-Replay: true</code>. Das Skript läuft '''nicht'''
|-
| Wiederholung, anderer Inhalt || '''422''' <code>IDEMPOTENCY_KEY_REUSED</code> - derselbe Schlüssel für einen anderen Inhalt ist ein Client-Fehler
|-
| Erster Aufruf läuft noch || '''503''' <code>IDEMPOTENCY_IN_PROGRESS</code> mit <code>Retry-After</code>. Beim nächsten Versuch liegt die gespeicherte Antwort vor
|-
| Früherer Aufruf ohne Ergebnis || '''409''' <code>IDEMPOTENCY_UNRESOLVED</code>. Nur noch nach einem '''harten Abbruch''' des Dienstes zwischen Verarbeitung und Festschreiben; ob die Buchung stattgefunden hat, ist unbekannt. Der Aufräumlauf gibt solche Einträge nach 24 Stunden frei und protokolliert sie
|}

Wichtig für die Auslegung eines Endpunkts:

* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* Antwortet das Skript mit '''4xx''' (fachliche Ablehnung), wird der Schlüssel wieder '''freigegeben''' - der Konsument darf ihn nach Korrektur erneut verwenden. Sonst würde ein einziger Validierungsfehler den Schlüssel dauerhaft blockieren.
* Endet die Verarbeitung mit '''5xx''' oder einem Skript-Fehler, wird der Schlüssel '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden.
* Das ist eine bewusste Abwägung (geändert 2026-08-25): Bleibt der Schlüssel nach einem Serverfehler belegt, ist der Vorgang '''unwiederholbar''' - der Client bekommt dauerhaft 503 und müsste die erfasste Arbeit verwerfen. Garantierter Datenverlust wiegt schwerer als ein möglicher Doppelsatz.
* '''Folge für die Auslegung:''' ein schreibender Endpunkt sollte selbst wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.

Der Schlüssel gilt je '''Zugang, Methode und Pfad'''. Derselbe
<code>Idempotency-Key</code> an einem anderen Endpunkt ist damit ein eigener
Vorgang - der Konsument muss ihn nicht global eindeutig vergeben, aber pro Vorgang
'''stabil wiederverwenden''' (also nicht bei jedem Wiederholversuch neu erzeugen).

Die Einträge stehen in <code>RESTSRV_IDEMPOTENCY</code> und werden nach 30 Tagen
automatisch aufgeräumt. Einträge ohne Ergebnis werden '''nicht''' automatisch
gelöscht, sondern im Protokoll gemeldet.

== WebHooks ==

WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
gespeichert und der Endpunkt anschließend automatisch gelöscht.

Typischer Einsatz: OBS stösst einen Vorgang bei einem Fremdsystem an (Bezahldienst,
Versanddienstleister) und gibt diesem eine Rückruf-Adresse mit, die nur '''ein
einziges Mal''' gültig ist. Damit kann die Adresse nicht später erneut - oder von
jemand anderem - benutzt werden.

Ablauf:

# OBS legt einen Eintrag in <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, dessen Feld '''WebHook''' (<code>re_webhook</code>) auf diesen Eintrag zeigt. Ein Skript wird für diesen Endpunkt nicht gepflegt.
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
# Das Fremdsystem ruft die Adresse auf. Der Server legt den übergebenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code> ab, antwortet mit <code>{"status": "ok"}</code> und '''löscht den Endpunkt'''.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.

{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
normalen Endpunkt mit Skript anlegen.}}

OBS/Stammdaten/Schnittstellen/Lagerlieferanten/OEX/Assmann

2026-08-27T08:54:21Z

Rademacker: Die Seite wurde neu angelegt: „= OEX-Schnittstelle: Assmann = Herstellerspezifische Besonderheiten der OEX-Anbindung an '''Assmann'''. Die allgemeine Beschreibung von Umfang, Voraussetzungen und Ablauf steht auf der Hauptseite. {| class="wikitable" ! Merkmal !! Wert |- | Standardversion || 3.0 |- | Status || '''vorbereitet''' – die Anbindung geht demnächst produktiv |- | Übertragungsart in OBS || „OEX Assmann" |} == 1 Aktueller Stand == Die Anbindung ist…“

= OEX-Schnittstelle: Assmann =

Herstellerspezifische Besonderheiten der OEX-Anbindung an '''Assmann'''. Die allgemeine Beschreibung von Umfang, Voraussetzungen und Ablauf steht auf der [[OEX-Schnittstelle|Hauptseite]].

{| class="wikitable"
! Merkmal !! Wert
|-
| Standardversion || 3.0
|-
| Status || '''vorbereitet''' – die Anbindung geht demnächst produktiv
|-
| Übertragungsart in OBS || „OEX Assmann"
|}

== 1 Aktueller Stand ==

Die Anbindung ist in OBS vollständig umgesetzt: Bestellungen an Assmann werden nach Standardversion 3.0 erzeugt, geprüft und im Ablageverzeichnis hinterlegt.

'''Noch nicht aktiv ist die automatische Übertragung.''' Bis zum Produktivstart wird die Bestelldatei erzeugt und abgelegt, aber nicht selbsttätig an Assmann übermittelt; der Anwender erhält beim Export einen entsprechenden Hinweis. Der Übertragungsweg wird zum Produktivstart eingerichtet.

Vor dem ersten produktiven Einsatz bitte den OBS-Support ansprechen.

== 2 Ablage und Protokoll ==

{| class="wikitable"
! Was !! Ort
|-
| Erzeugte Dateien || <code><OBS-Verzeichnis>\data\oex\</code>
|-
| Protokolldatei || <code><OBS-Verzeichnis>\data\oex\oex_proto.txt</code>
|}

== Siehe auch ==

* [[OBS/Stammdaten/Schnittstellen/Lagerlieferanten/OEX|OEX-Schnittstelle]] – allgemeine Beschreibung der Schnittstelle

OBS/Stammdaten/Schnittstellen/Lagerlieferanten/OEX/Steelcase

2026-08-27T08:53:30Z

Rademacker: Die Seite wurde neu angelegt: „= OEX-Schnittstelle: Steelcase = Herstellerspezifische Besonderheiten der OEX-Anbindung an '''Steelcase'''. Die allgemeine Beschreibung von Umfang, Voraussetzungen und Ablauf steht auf der Hauptseite. {| class="wikitable" ! Merkmal !! Wert |- | Standardversion || 2.1 |- | Übertragungsweg || Direktübertragung per Web-Service in das Steelcase-SAP |- | Status || produktiv im Einsatz |- | Übertragungsart in OBS || „OEX Steelcase"…“

= OEX-Schnittstelle: Steelcase =

Herstellerspezifische Besonderheiten der OEX-Anbindung an '''Steelcase'''. Die allgemeine Beschreibung von Umfang, Voraussetzungen und Ablauf steht auf der [[OEX-Schnittstelle|Hauptseite]].

{| class="wikitable"
! Merkmal !! Wert
|-
| Standardversion || 2.1
|-
| Übertragungsweg || Direktübertragung per Web-Service in das Steelcase-SAP
|-
| Status || produktiv im Einsatz
|-
| Übertragungsart in OBS || „OEX Steelcase"
|}

== 1 Übertragungsweg ==

Steelcase nutzt nicht den im Standard vorgesehenen Mailversand, sondern einen '''gesicherten Web-Service'''. OBS übergibt die Bestellung unmittelbar an das Steelcase-SAP.

{| class="wikitable"
! Merkmal !! Umsetzung
|-
| Protokoll || HTTPS, verschlüsselte Verbindung
|-
| Übergabe || die erzeugte XML-Datei wird an den konfigurierten Endpunkt übergeben
|-
| Authentifizierung || Signaturverfahren über Zeitstempel, Einmalkennung, Anfrage-Kennung und Partnerkennung
|-
| Dienst || Bestellung
|-
| Rückmeldung || die Antwort des Steelcase-Systems wird im OEX-Protokoll festgehalten
|}

Die Bestellung ist damit unmittelbar nach dem Export im Herstellersystem – es gibt keinen Mailversand und keine Wartezeit im Postausgang.

=== 1.1 Zugangsdaten ===

In der Konfiguration des Lagerlieferanten sind drei Werte zu hinterlegen. Alle drei kommen von Steelcase.

{| class="wikitable"
! Eintrag !! Bedeutung
|-
| Endpunkt || Adresse des Web-Service bei Steelcase
|-
| Key || eindeutige Identifikation für den Zugang (Partnerkennung)
|-
| Secret Key || Authentifizierungs-Token; wird verschlüsselt gespeichert und nicht im Klartext angezeigt
|}

Sind die Werte nicht vollständig hinterlegt, wird die Bestelldatei erzeugt und abgelegt, aber '''nicht übertragen'''. Im OEX-Protokoll erscheint dann ein Hinweis auf die unvollständige Konfiguration. Das ist der häufigste Grund dafür, dass eine Bestellung beim Hersteller nicht ankommt, obwohl OBS keinen Fehler meldet.

== 2 Was der Anwender selbst beachten muss ==

=== 2.1 Nur ein Vertriebsgebiet pro Bestellung ===

'''Artikel aus unterschiedlichen Vertriebsgebieten – DACH und EMEA – dürfen nicht in derselben Bestellung gemischt werden.'''

Die Schnittstelle prüft das '''nicht'''. Eine gemischte Bestellung wird technisch fehlerfrei übertragen und schlägt erst bei der Verarbeitung im Steelcase-SAP auf. Der Anwender muss die Bestellung daher vor dem Export prüfen und gegebenenfalls nach Vertriebsgebiet in zwei Bestellungen aufteilen.

=== 2.2 Zahlungs- und Lieferbedingungen ===

OBS überträgt die Zahlungsbedingungen aus dem Stamm mit, '''Steelcase ignoriert sie jedoch'''. Führend sind ausschließlich die im Steelcase-SAP hinterlegten Konditionen. Die Angaben in der Datei dienen nur der Information.

Abweichende Konditionen für eine einzelne Bestellung lassen sich daher '''nicht''' über die Schnittstelle vereinbaren – das muss vorab direkt mit Steelcase geklärt und dort hinterlegt werden.

== 3 Vorgaben von Steelcase ==

{| class="wikitable"
! Thema !! Vorgabe
|-
| Absenderkennung im Dateinamen || Aufbau von Steelcase vorgegeben: Kundennummer, Mandant und Bestellnummer
|-
| Applikationskennung || OBS meldet sich mit der von Steelcase vorgegebenen Kennung an
|}

== 4 Ablage und Protokoll ==

Wie bei allen OEX-Bestellungen:

{| class="wikitable"
! Was !! Ort
|-
| Erzeugte Dateien || <code><OBS-Verzeichnis>\data\oex\</code>
|-
| Protokolldatei || <code><OBS-Verzeichnis>\data\oex\oex_proto.txt</code>
|}

Bei Rückfragen zu einer Bestellung enthält das Protokoll neben dem Dateinamen auch die Anfrage-Kennungen der Übertragung und die Antwort des Steelcase-Systems. Diese Kennungen sind bei Rückfragen an Steelcase anzugeben.

== Siehe auch ==

* [[OBS/Stammdaten/Schnittstellen/Lagerlieferanten/OEX|OEX-Schnittstelle]] – allgemeine Beschreibung der Schnittstelle

OBS/Stammdaten/Schnittstellen/Lagerlieferanten/OEX

2026-08-27T08:36:58Z

Rademacker: Die Seite wurde neu angelegt: „= OEX-Schnittstelle (OFML Business Data Exchange) = Die OEX-Schnittstelle überträgt Möbelbestellungen aus OBS elektronisch an den Hersteller – inklusive der vollständigen OFML-Konfiguration jeder Position. Sie ersetzt den manuellen Bestellweg per PDF und Mail für Hersteller der Büro- und Objektmöbelbranche. OEX ist ein offener Branchenstandard des '''Industrieverbands Büro und Arbeitswelt e. V. (IBA)''' und Teil der OFML-Standardfamilie. {| c…“

= OEX-Schnittstelle (OFML Business Data Exchange) =

Die OEX-Schnittstelle überträgt Möbelbestellungen aus OBS elektronisch an den Hersteller – inklusive der vollständigen OFML-Konfiguration jeder Position. Sie ersetzt den manuellen Bestellweg per PDF und Mail für Hersteller der Büro- und Objektmöbelbranche.

OEX ist ein offener Branchenstandard des '''Industrieverbands Büro und Arbeitswelt e. V. (IBA)''' und Teil der OFML-Standardfamilie.

{| class="wikitable"
! Merkmal !! Wert
|-
| Standard || OEX – OFML Business Data Exchange
|-
| Herausgeber || Industrieverband Büro und Arbeitswelt e. V. (IBA)
|-
| Datenformat || XML
|-
| Zeichensatz || UTF-8
|-
| Umgesetzte Standardversionen || 2.1 und 3.0
|-
| Umgesetzter Beleg || Bestellung
|-
| OBS-Modul || OEX (separat freizuschalten)
|-
| Einordnung in OBS || Lagerlieferanten-Übertragungsart
|}

== 1 Funktionsumfang ==

=== 1.1 Umgesetzter Beleg ===

Umgesetzt ist die '''Bestellung''' in Richtung Hersteller. Sie geht vollständig elektronisch heraus, mit allen Positionen, Konfigurationsmerkmalen, Texten und Adressen.

Rückmeldungen des Herstellers – Bestellbestätigung, Lieferavis, Rechnung – werden weiterhin auf dem bisherigen Weg verarbeitet (Mail, Papier, Portal). Auch Änderungen oder Stornos zu einer bereits übertragenen Bestellung werden nicht elektronisch nachgeschickt, sondern direkt mit dem Hersteller abgestimmt.

=== 1.2 Umgesetzte Standardversionen ===

Der OEX-Standard liegt in mehreren Versionen vor. OBS beherrscht die beiden in der Branche verbreiteten Versionen '''2.1''' und '''3.0''' und erzeugt aus derselben Programmlogik die jeweils passende Datei.

Welche Version zum Einsatz kommt, gibt der Hersteller vor – sie ist nicht frei wählbar und wird bei der Einrichtung der Anbindung festgelegt. Für den Anwender macht das im Arbeitsablauf keinen Unterschied; die Unterschiede liegen im Umfang der übertragenen Daten (siehe Abschnitt 8).

Damit ist OBS unabhängig davon anschlussfähig, ob ein Hersteller noch auf der älteren Version arbeitet oder bereits die aktuelle einsetzt.

== 2 Voraussetzungen ==

=== 2.1 Modul und Lizenz ===

Die Schnittstelle erfordert das freigeschaltete '''OBS-Modul „OEX"'''. Ist es nicht aktiv, bricht der Export mit einem entsprechenden Hinweis ab. Die Nutzung wird protokolliert und gezählt.

=== 2.2 OFML-Datenbasis (zwingend) ===

Dies ist die wichtigste Voraussetzung und der häufigste Grund für Rückfragen:

'''Eine OEX-Bestellung lässt sich nur aus Positionen erzeugen, die aus einer OFML-Planung stammen.'''

Der Hersteller braucht nicht nur die Artikelnummer, sondern die vollständige Konfiguration – Serie, Variantencode, alle Merkmale mit ihren Werten. Diese Informationen entstehen im Planungswerkzeug, typischerweise '''pCon.planner''' oder '''pCon.basket''', und gelangen über den '''OBX-Import''' in den OBS-Vorgang.

Datenfluss:

Planung (pCon) → OBX-Datei → OBX-Import in Angebot/Auftrag → Bestellung → OEX-Export → Hersteller

Der OBX-Import übernimmt je Position:

* Hersteller-Kennung und Serie
* Artikelnummer in den Varianten Basis-, Final- und Variantencode
* Kurztext, Langtext und Ausstattungstext
* alle Konfigurationsmerkmale mit Bezeichnung und Wert
* Menge
* EK- und VK-Preis (Währung EUR), Positions- und Lieferantenrabatt
* Ordnerstruktur und Unterpositionen der Planung
* Zusatztexte aus der Planung
* Bilder der Planung (optional)

Zusätzlich wird die komplette Original-Konfiguration als Rückverweis gespeichert. In Version 3.0 wird dieser Rückverweis mit der Bestellung übertragen, sodass der Hersteller die Planung auf seiner Seite wieder öffnen kann.

Manuell in OBS angelegte Positionen und Positionen aus dem normalen Artikelstamm haben keine OFML-Daten und können nicht per OEX bestellt werden.

=== 2.3 Stammdaten ===

{| class="wikitable"
! Was !! Wo !! Bemerkung
|-
| Übertragungsart des Lieferanten || Lagerlieferant || die OEX-Übertragungsart des jeweiligen Herstellers
|-
| Eigene Kundennummer beim Lieferanten || Bestellung / Lieferantenstamm || '''Pflicht''' – ohne diese Nummer bricht der Export ab
|-
| Hersteller-Zuordnung der OFML-Kennung || wird beim OBX-Import einmalig abgefragt || ordnet die OFML-Hersteller-Kennung dem OBS-Lieferanten zu
|-
| Zugangsdaten des Übertragungswegs || Konfiguration des Lagerlieferanten || nur bei Herstellern mit Direktübertragung, siehe Abschnitt 6
|-
| Währung, Land, Zahlungsbedingung || Standard-Stammdaten || für Belegwährung, ISO-Länderkennung und Zahlungsbedingungen
|-
| Mandantenadresse || Konstanten des Mandanten || wird als Auftraggeber-Adresse übertragen
|-
| Sachbearbeiter mit Telefon und E-Mail || Verkäuferstamm || wird als Ansprechpartner übertragen
|}

== 3 Einrichtung ==

# '''Modul freischalten''' – über den OBS-Support.
# '''Lieferant als Lagerlieferant einrichten''' und die OEX-Übertragungsart des Herstellers setzen.
# '''Eigene Kundennummer beim Lieferanten''' eintragen.
# '''Übertragungsweg einrichten.''' Wie die Datei zum Hersteller kommt und welche Zugangsdaten dafür nötig sind, gibt der Hersteller vor – Details auf der jeweiligen Unterseite (siehe Abschnitt 10).
# '''Testbestellung''' mit dem Hersteller abstimmen und durchführen.

== 4 Ablauf im Tagesgeschäft ==

# Planung in pCon erstellen und als OBX-Datei exportieren.
# OBX-Datei in das OBS-Angebot bzw. den Auftrag importieren. Die OFML-Daten bleiben an den Positionen hängen und werden bei der Übernahme in Folgevorgänge mitgeführt.
# Bestellung zum Lieferanten erzeugen.
# Bestellung exportieren. Es erscheint die Rückfrage, ob die Bestellung wirklich exportiert werden soll.
# OBS prüft die Positionen auf Vollständigkeit, erzeugt die XML-Datei und überträgt sie an den Hersteller.
# Die Bestellung wird auf die Übertragungsart „Export" gesetzt. Der Vorgang wird im OEX-Protokoll festgehalten.

=== 4.1 Vollständigkeitsprüfung vor dem Export ===

Vor dem Erzeugen der Datei prüft OBS '''jede''' Position. Fehlt eine der folgenden Angaben, wird der Export abgebrochen und alle betroffenen Positionen werden mit Positionsnummer, Bezeichnung und Fehlergrund aufgelistet:

{| class="wikitable"
! Meldung !! Bedeutung / Abhilfe
|-
| keine OFML-Daten vorhanden || Die Position stammt nicht aus einer OFML-Planung. Position über OBX-Import einfügen oder aus der Bestellung entfernen.
|-
| OFML-Bestellnummer fehlt || Die Planungsdaten enthalten keine Bestellartikelnummer. Planung im Planungswerkzeug prüfen.
|-
| OFML-Hersteller fehlt || Die Hersteller-Kennung fehlt in den Planungsdaten.
|-
| OFML-Serie fehlt || Die Serienangabe fehlt in den Planungsdaten.
|}

Zusätzlich wird geprüft, ob die eigene Kundennummer beim Lieferanten eingetragen ist. Fehlt sie, erscheint der Hinweis, dass eine OEX-Bestellung nur mit eingetragener Kundennummer möglich ist.

=== 4.2 Erneutes Versenden ===

Ein zweiter Export derselben Bestellung erzeugt beim Hersteller eine zweite Bestellung – jede Datei ist inhaltlich eine Neuanlage. Ein erneutes Versenden muss deshalb immer mit dem Hersteller abgesprochen sein.

== 5 Übertragener Inhalt ==

Die Bestellung wird '''vollständig''' übertragen, also mit allen Positionen. Belegkopf und Positionen sind als Neuanlage gekennzeichnet.

=== 5.1 Belegkopf ===

{| class="wikitable"
! Inhalt !! Herkunft in OBS
|-
| Bestellnummer || Bestellung
|-
| Kundennummer beim Lieferanten || Bestellung
|-
| Lieferantennummer || Bestellung
|-
| Belegwährung || Währungsstamm
|-
| Teillieferung erlaubt || fest „nein"
|-
| Belegsprache || fest „deutsch"
|-
| Auftragsart || fest „Standardauftrag"
|-
| Belegdatum || Bestelldatum
|-
| Wunschliefertermin || Lieferdatum der Bestellung
|-
| Rahmenvertragsnummer || OFML-Text „Sonderkondition" des Vorgangs
|-
| Kommission || Auftragsnummer des Endkunden
|-
| Verkaufsorganisation || Mandant
|-
| Abwicklungsmodalitäten (Text) || OFML-Text „Lieferbedingung" des Vorgangs
|-
| Verweis auf Anhang || Bestell-PDF (<code>BE<Bestellnummer>.pdf</code>)
|-
| Gesamtnetto || Nettobetrag der Bestellung, als Information
|-
| Zahlungsbedingungen || Zahlungsbedingungsstamm: Skontotage und -satz, zweite Skontostufe, Nettoziel (bis zu drei Staffeln)
|}

'''Adressen'''

{| class="wikitable"
! Adressart !! Inhalt !! Ansprechpartner
|-
| Auftraggeber || Adresse des eigenen Mandanten, mit der Kundennummer beim Lieferanten || Sachbearbeiter aus dem Verkäuferstamm mit Telefon und E-Mail
|-
| Lieferant || Bestelladresse des Lieferanten || Ansprechpartner mit Telefonnummer
|-
| Anlieferadresse || Versandadresse der Bestellung; ist keine hinterlegt, die Adresse des Mandanten (eigenes Lager) ||
|}

Die Länderkennung wird als ISO-Länderkennung mit zwei Zeichen übertragen; ist im Land keine hinterlegt, wird „DE" verwendet.

=== 5.2 Positionen ===

{| class="wikitable"
! Inhalt !! Herkunft in OBS
|-
| Positionsnummer || Bestellposition
|-
| übergeordnete Position || OFML-Struktur (Unterpositionen, Stücklisten)
|-
| Kundenartikelnummer || Artikelnummer der Bestellposition
|-
| Lieferantenartikelnummer || OFML-Bestellnummer, mit Artikelstatus (Original / modifiziert)
|-
| Lieferantenkennung || OFML-Hersteller
|-
| Serie || OFML-Serie
|-
| Bestellmenge || Menge der Bestellposition
|-
| Mengeneinheit || fest „Stück"
|-
| Konfigurationsmerkmale || alle OFML-Merkmale der Position mit Bezeichnung und Wert
|-
| Positions-ID || formatierte Positionsnummer
|-
| Konfigurations-ID || OFML-Variantencode
|-
| Abladeangabe || OFML-Text „Abladeangabe" – z. B. „1. OG, Herr Huber", wird beim Hersteller auf die Packstücke gedruckt
|-
| Artikelkurztext || Bezeichnung 1 und 2 der Bestellposition
|-
| Artikellangtext || OFML-Langtext und Ausstattungstext
|-
| modifizierter Artikeltext || OFML-Zusatztext, sofern vorhanden
|-
| Nettogesamtpreis || Gesamtpreis der Bestellposition
|-
| Rückverweis auf die Konfiguration || Original-Planungsdaten (nur Version 3.0)
|}

In Version 3.0 wird zusätzlich die '''Ordnerstruktur''' der Planung als eigene Ordnerpositionen übertragen, sodass die Gliederung beim Hersteller erhalten bleibt. Version 2.1 kennt keine Ordnerpositionen.

'''Artikelstatus''': Positionen mit modifiziertem Artikeltext werden als „modifiziert" gekennzeichnet, alle anderen als „Original-Artikel des Lieferanten". Der Hersteller erkennt daran, ob er den Artikel unverändert produzieren kann oder ob eine Sonderbearbeitung anfällt.

=== 5.3 Preise ===

Übertragen wird das '''Gesamtnetto''' – im Kopf für die Bestellung, je Position der Nettogesamtpreis – jeweils als Einkaufskondition. Rabatte, Zuschläge, Zwischensummen und Steuersätze werden '''nicht''' einzeln übertragen. Die Preise dienen dem Abgleich; führend für die Fakturierung ist das System des Herstellers.

== 6 Übermittlung ==

Der OEX-Standard sieht als Übermittlungsweg den '''E-Mail-Anhang''' zwischen zwei vereinbarten Adressen vor. Zusätzliche Anhänge wie das Bestell-PDF werden im Dokument als Verweis aufgeführt.

Einzelne Hersteller stellen stattdessen einen eigenen Web-Service für die '''Direktübertragung''' bereit. OBS übergibt die Bestellung dann unmittelbar und gesichert an das System des Herstellers – ohne Mailversand, ohne manuellen Zwischenschritt und ohne Wartezeit im Postausgang. Die Antwort des Herstellersystems wird im OEX-Protokoll festgehalten.

Für die Direktübertragung sind Endpunkt und Zugangsdaten in der Konfiguration des Lagerlieferanten zu hinterlegen; der Authentifizierungs-Token wird verschlüsselt gespeichert und nicht im Klartext angezeigt. Welche Werte einzutragen sind, gibt der Hersteller vor – siehe die jeweilige Unterseite (Abschnitt 10).

Ist für einen Hersteller keine Direktübertragung eingerichtet, wird die Datei erzeugt und abgelegt, aber nicht automatisch übertragen; der Anwender erhält einen entsprechenden Hinweis.

== 7 Dateien, Pfade und Protokoll ==

{| class="wikitable"
! Was !! Ort
|-
| Erzeugte OEX-Dateien || <code><OBS-Verzeichnis>\data\oex\</code>
|-
| Protokolldatei || <code><OBS-Verzeichnis>\data\oex\oex_proto.txt</code>
|}

'''Dateinamen''' folgen dem Muster des Standards:

oex-orders_<Absenderkennung>_jjjjmmtt-hhmmss.xml

Als Absenderkennung verwendet OBS die Kombination aus Kundennummer beim Lieferanten, Mandant und Bestellnummer. Einzelne Hersteller geben den Aufbau der Absenderkennung ausdrücklich vor.

Das '''Protokoll''' hält je Vorgang mit Zeitstempel und Benutzerkennung fest: Start des Exports, erzeugter Dateiname, Beginn der Übertragung, Anfrage-Kennungen, die Antwort des Herstellersystems sowie jede aufgetretene Fehlermeldung. Es ist die erste Anlaufstelle bei Rückfragen zu einer Bestellung.

== 8 Unterschiede der Versionen 2.1 und 3.0 ==

Beide Versionen übertragen denselben Kern: Bestellkopf, Adressen, Positionen mit vollständiger Konfiguration, Texte und Preise. Version 3.0 geht darüber hinaus:

{| class="wikitable"
! Thema !! Version 2.1 !! Version 3.0
|-
| Ordnerstruktur der Planung || nicht vorgesehen || wird als eigene Ordnerpositionen übertragen
|-
| Rückverweis auf die Planungsdaten || nicht vorgesehen || wird mitgeliefert, der Hersteller kann die Planung wieder öffnen
|-
| Set-Artikel und reine Textpositionen || nicht vorgesehen || eigene Positionsarten vorhanden
|-
| Identifikation der Partner || über die internationale Lokationsnummer (ILN) || über Kunden- und Lieferanten-ID mit Klassifizierung
|-
| Vorgängerbeleg (z. B. Angebot) || nicht im Kopf abbildbar || eigene Felder im Kopf und je Position
|-
| Katalog-Kennung, Variantencode, Unterartikel || nicht vorgesehen || vorhanden
|-
| Eindeutige Kennung je Position || nicht vorgesehen || jede Position trägt eine eindeutige Kennung
|}

Praktisch heißt das: Bei einem Hersteller auf Version 3.0 bleibt die Gliederung der Planung erhalten und der Hersteller kann die Konfiguration auf seiner Seite nachvollziehen. Bei Version 2.1 wird die Bestellung als flache Positionsliste übertragen – inhaltlich vollständig, aber ohne Gliederung und ohne Rückverweis.

== 9 Grenzen und bewusste Festlegungen ==

Die Schnittstelle ist auf den Bestellprozess ausgelegt. Folgendes ist nicht enthalten:

* '''Nur die Bestellung, nur ausgehend''' (siehe 1.1).
* '''Auftragsart fest Standardauftrag.'''
* '''Mengeneinheit fest Stück.'''
* '''Keine Teillieferungen''' – es wird immer „Teillieferung nicht erlaubt" übertragen.
* '''Belegsprache fest deutsch.'''
* '''Keine Gewichts- und Volumenangaben, keine Lieferbedingungen nach Inco-Terms, keine EAN, keine Bankdaten, kein separater Rechnungsempfänger.'''
* '''Rabatte, Zuschläge und Steuersätze''' werden nicht einzeln übertragen (siehe 5.3).
* '''Ein Beleg pro Datei''' – jede Bestellung wird als eigene Datei übertragen, es werden keine Bestellungen gebündelt.

== 10 Herstellerspezifische Besonderheiten ==

Jeder Hersteller legt die eingesetzte Standardversion, den Übertragungsweg, die Zugangsdaten und einzelne Detailvorgaben selbst fest. Diese Besonderheiten sind je Hersteller auf einer eigenen Unterseite dieser Seite dokumentiert.

Vor der ersten Bestellung an einen Hersteller sollte die zugehörige Unterseite gelesen werden – dort stehen die Punkte, die der Anwender selbst beachten muss und die die Schnittstelle nicht prüfen kann.

== 11 Nutzen im Überblick ==

* '''Keine Doppeleingabe.''' Die Planung wandert vom Planungswerkzeug über Angebot und Auftrag bis in die Bestellung des Herstellers, ohne dass Konfigurationen erneut erfasst werden.
* '''Keine Übertragungsfehler.''' Serie, Variantencode und alle Merkmale gehen maschinenlesbar heraus statt als Freitext im PDF.
* '''Vollständigkeitsprüfung vorab.''' Unvollständige Positionen fallen in OBS auf, nicht erst beim Hersteller.
* '''Schnellere Auftragsbestätigung''', weil beim Hersteller keine manuelle Erfassung dazwischen liegt.
* '''Nachvollziehbarkeit.''' Datei und Protokoll dokumentieren, was wann an wen übertragen wurde.
* '''Rauminformationen bis auf das Packstück.''' Abladeangaben aus der Planung werden mitgegeben und beim Hersteller auf die Packstücke gedruckt.
* '''Breite Anschlussfähigkeit.''' Mit den Versionen 2.1 und 3.0 sind beide in der Branche verbreiteten Stände umgesetzt; weitere Hersteller lassen sich mit begrenztem Aufwand anbinden.

== 12 Begriffe ==

{| class="wikitable"
! Begriff !! Bedeutung
|-
| OFML || Datenstandard der Möbelbranche für Artikel-, Konfigurations- und Preisdaten
|-
| OEX || Standard für den elektronischen Austausch von Geschäftsdokumenten innerhalb der OFML-Familie
|-
| OBX || Austauschformat der Planungswerkzeuge für Planungsinhalte („Warenkorb"); Eingangsformat für OBS
|-
| pCon.planner / pCon.basket || verbreitete Planungswerkzeuge der Branche, liefern die OBX-Dateien
|-
| IBA || Industrieverband Büro und Arbeitswelt e. V., Herausgeber des Standards
|-
| Variantencode || Kurzschlüssel, der eine konkrete Artikelkonfiguration eindeutig beschreibt
|-
| Abladeangabe || Zusatzinformation zum Anlieferort einer Position, z. B. Etage und Raum
|-
| ILN || Internationale Lokationsnummer zur Identifikation von Geschäftspartnern (Version 2.1)
|}

OBS/Kostenpflichtige Module/RESTServer/Zugaenge

2026-08-20T07:30:52Z

Rademacker:

{{Kostenpflichtige Module}}

=Zugänge=

Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''

==Felder==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Name || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
| CORS-Origins || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt. '''Leer heisst nicht „keine Einschränkung", sondern „kein Browser-Zugriff"''' - siehe unten
|-
| mTLS-Subject || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
|-
| JWT || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
| JWT-Endpunkt || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
|-
| JWT-Key || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
| JWT-Exp || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
|}

==API-Key==

Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:

apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12

Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.

{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}

==Host-Beschränkung==

Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.

==CORS==

Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.

Format der Liste:

https://app.kunde.de;https://test.kunde.de;https://localhost:8080

Ablauf:

# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste '''aller''' Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste '''des aktuell verwendeten Zugangs''' geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.

Der Preflight kann nicht zugangsbezogen prüfen: der Browser schickt dabei keinen
''apikey'' mit, der Zugang ist zu diesem Zeitpunkt unbekannt. '''Die Durchsetzung
liegt deshalb auf Schritt 2''', nicht auf dem Preflight. Praktische Folge: trägt
'''ein''' Zugang auf dem Server ein ''*'' in seiner Liste, antwortet jeder
Preflight mit ''Access-Control-Allow-Origin: *'' - auch für Zugänge mit engerer
Liste. Deren eigentliche Anfrage wird trotzdem gegen die eigene Liste geprüft.

Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH'' (systemseitig festgelegt).

Bei den '''Anfrage-Headern''' spiegelt der Server im Preflight zurück, was der
Browser in ''Access-Control-Request-Headers'' angefragt hat. Damit sind eigene
Header eines Projekts - ''Idempotency-Key'', ''If-Match'', später
''Upload-Offset''/''Upload-Length'' - ohne Änderung am Server nutzbar. Fragt der
Preflight keine Header an, antwortet der Server mit der Liste
''Content-Type, apikey, Authorization, Accept''.

{{Hinweis|Die Header-Liste ist '''keine Schutzgrenze''' - das ist das Origin. Sie
sagt dem Browser nur, welche Header der Server versteht. Dazu kommt, dass die
Zugangsdaten dieser Schnittstelle in Headern stehen (''apikey'',
''Authorization'') und nicht in Cookies: es gibt also keine automatisch
mitgeschickte Berechtigung, die eine fremde Seite ausnutzen könnte.}}

===Was „leer" bedeutet===

{{Achtung|Ein '''leeres''' Feld CORS-Origins heisst '''nicht''' „keine
Einschränkung". Es heisst: '''jeder Aufruf mit ''Origin''-Header wird mit 403
abgelehnt'''. Für Clients '''ohne''' ''Origin''-Header - mobile Apps, Server,
curl - ändert das Feld gar nichts, sie werden nie gegen CORS geprüft.}}

Daraus ergeben sich drei sinnvolle Einstellungen:

{| class="wikitable"
! Feld !! Wirkung
|-
| leer || Kein Browser-Zugriff. Richtig für Zugänge, die nur von Apps oder Servern benutzt werden
|-
| konkrete Origins || Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen
|-
| ''*'' || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antwort aller anderen Zugänge - bewusst und sparsam verwenden
|}

Für eine Browser-Anwendung ist dieses Feld besonders wichtig, weil ihr API-Key
zwangsläufig im JavaScript liegt und damit öffentlich ist. Die Origin-Liste
verhindert dann, dass jemand den Key nimmt und von seiner eigenen Seite benutzt.
Sie ist allerdings kein Ersatz für eine Zugriffskontrolle: wer den Key hat,
umgeht CORS mit einem einzigen Aufruf ausserhalb des Browsers.

==JWT-Authentifizierung==

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).

'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.

Unterschieden wird nach Verb und Token-Art:

{| class="wikitable"
! Aufruf !! Ablauf
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
|}

{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}

===Phase 1: Token-Bezug===

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Body: {"username":"...", "password":"..."}

Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Funktion ''Authenticate'' bereitstellen, die ein JSON-Objekt mit:

* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_<name>'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)

zurückliefert. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 28800,
"serverTime": "2026-06-29T15:30:12+02:00"}

Zum Aufbau der Antwort:

* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.

Beispiel mit Zusatzfeldern aus dem Skript:

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
"expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}

Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.

Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''' und reicht den Text aus dem Feld ''error'' als
''error.message'' an den Client durch - der Konsument kann ihn also direkt
anzeigen. Die Formulierung liegt damit beim Skript.

{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}

===Phase 2: Token-Verwendung===

Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:

GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi...

Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.

Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.

{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}

===Phase 3: Token erneuern (Refresh)===

Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Refresh-Token)

Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}

Verhalten bei einem bereits benutzten Refresh-Token:

{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
|}

Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

===Phase 4: Abmelden (Logout)===

Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
Access-Token im ''Authorization''-Header:

DELETE https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Access-Token)

HTTP/1.1 204 No Content

Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.

* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.

====Alle Geräte abmelden====

Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
Antwortfeld ''_OBS_JWT_REVOKE'', das jeder gewöhnliche Endpunkt setzen kann:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
oRes := TJSONObject.Create();
try
// 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
oRes.AddPair('_OBS_JWT_REVOKE' , 'all');
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}

==Sitzungen (RESTSRV_TOKEN)==

Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt".

* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.

==mTLS-Subject-Prüfung==

Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.

Beispiele für Subject-Strings im Cert (OneLine-DN):

/C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
/C=DE/O=Kunde GmbH/CN=client-test.kunde.de

Mit '''CN=client-prod.kunde.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Kunde GmbH;CN=client-prod.kunde.de''.

==Listen-Funktionen==

In der Zugänge-Liste (allein):

* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang

Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):

* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

OBS/Kostenpflichtige Module/RESTServer/Beispiel5

2026-08-19T12:01:01Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz=

Dieses Beispiel zeigt einen schreibenden Endpunkt für eine mobile App: Aufträge werden mit echten HTTP-Statuscodes aktualisiert, konkurrierende Änderungen über ETag/If-Match abgesichert (Optimistic Concurrency) und doppelte Sendungen über einen Idempotency-Key abgefangen. Die Anmeldung nutzt JWT mit Custom-Claims (Mandant, Rollen) und einem Refresh-Token.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App''
** API-Key: zufällig generiert
** JWT aktiv, JWT-Endpunkt ''auth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
* '''Endpunkte''' (beide dem Profil ''Public-API'' zugeordnet):
** ''orders/{uid}'' - Auftrag lesen/Ändern
** ''orders/{uid}/material'' - Material erfassen
* '''Berechtigung:''' Zugang ''Mobile-App'' für beide Endpunkte freigeschaltet

{{Hinweis|Für das Abmelden gibt es '''keinen eigenen Endpunkt'''. Es läuft über
ein ''DELETE'' auf den JWT-Endpunkt ''auth'' und braucht daher weder eine Zeile
in ''RESTSRV_ENDPOINTS'' noch eine Berechtigung.}}

==JWT-Authentifizierungs-Skript (Zugang)==

Stellt Mandant und Rollen als Custom-Claims aus und löst über ''_OBS_JWT_REFRESH_ID'' ein Refresh-Token aus. Bei einem Refresh ruft der Server im selben Skript die Methode ''Refresh'' auf. Die Hilfsfunktionen (''PasswortPasst'', ''TechnikerMandant'', ''TechnikerRollen'') sind illustrativ und projektabhängig.

{{Hinweis|Eine '''eigene Sperrtabelle für Refresh-jti ist nicht nötig'''.
Einmalgebrauch, Rotation und Widerruf führt der Server in ''RESTSRV_TOKEN'' -
das Skript entscheidet nur, '''ob''' und '''mit welchen Rechten''' die Sitzung
fortgesetzt wird. Frühere Fassungen dieses Beispiels zeigten eine Skript-Tabelle;
wer sie übernommen hat, kann sie entfernen.}}

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser, cPass: string;
begin
oRes := TJSONObject.Create();
try
cUser := ''; cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username'); if (Assigned(oVal)) then cUser := oVal.Value;
oVal := oBody.GetValue('password'); if (Assigned(oVal)) then cPass := oVal.Value;
end;

if (PasswortPasst(cUser, cPass)) then begin
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser)); // z.B. "tech,lead"
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das Refresh-Token aus
// _OBS_JWT_REFRESH_EXP weggelassen -> Default 90 Tage
end else begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Login fehlgeschlagen');
end;
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------

function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cUser: string;
begin
oRes := TJSONObject.Create();
try
cUser := oParams.Values['_OBS_JWT_SUBJECT'];

// Das vorgelegte Refresh-Token hat der Server bereits geprueft und
// entwertet. Hier wird nur entschieden, ob die Sitzung fortgesetzt
// werden darf - und mit welchen Rechten.
if (not TechnikerAktiv(cUser)) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
result := oRes.ToJSON();
exit;
end;

// Mandant und Rollen NEU lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID());
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}'' - ändern mit ETag / If-Match==

''GET'' liefert den Auftrag samt ''ETag'' (Version), ''PUT'' prüft Rolle und ''If-Match''.

<syntaxhighlight lang="pascal" line>
function Get(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
cUid: string;
nVer: integer;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];
if (not AuftragLesen(oParams.Values['_OBS_JWT_CLAIM_tenant'], cUid, oRes, nVer)) then begin
oRes.AddPair('_OBS_HTTP_STATUS', 404);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'NOT_FOUND'));
result := oRes.ToJSON();
exit;
end;
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nVer));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------

function Put(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
cUid: string;
nAktuell, nIfMatch: integer;
begin
oRes := TJSONObject.Create();
try
// nur Rolle "lead" darf ändern - Rolle kommt aus dem Token, nicht aus dem Body.
// Mit Trennzeichen suchen: ein blosses Pos('lead', ...) wuerde auch in
// "leadless" oder "teamlead" treffen.
if (Pos(',lead,', ',' + oParams.Values['_OBS_JWT_CLAIM_roles'] + ',') = 0) then begin
oRes.AddPair('_OBS_HTTP_STATUS', 403);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'FORBIDDEN_ROLE'));
result := oRes.ToJSON();
exit;
end;

cUid := oParams.Values['_OBS_PATH_uid'];
nAktuell := AuftragVersion(cUid);
nIfMatch := iVal(oParams.Values['if-match']);

if (nIfMatch <> nAktuell) then begin
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell));
oRes.AddPair('_OBS_HTTP_STATUS', 409);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'VERSION_CONFLICT'));
result := oRes.ToJSON();
exit;
end;

AuftragSpeichern(cUid, oBody); // setzt Version auf nAktuell + 1
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell + 1));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}/material'' - idempotentes Anlegen==

''POST'' erfasst eine Materialposition: Validierungsfehler -> 422, erfolgreiches Anlegen -> 201.

Gegen doppelte Sendungen schickt der Client den Header ''Idempotency-Key''. '''Das
Skript muss dafür nichts tun''' - der Server erkennt den Header, merkt sich das
Ergebnis und liefert bei einer Wiederholung mit demselben Schlüssel die
gespeicherte Antwort zurück, ohne das Skript erneut zu starten (siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz). Das Skript kümmert sich nur um seine Fachlogik:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
oVal: TJSONValue;
cUid, cArtikel, cNeueUid: string;
nMenge: integer;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];

// 1) Validierung -> 422 mit traceId.
// Wichtig: fachliche Ablehnung als 4xx melden, nicht als 200 mit
// Fehlertext - nur dann gibt der Server den Idempotency-Key wieder
// frei und der Client darf ihn nach Korrektur erneut verwenden.
cArtikel := '';
nMenge := 0;
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('artikel'); if (Assigned(oVal)) then cArtikel := oVal.Value;
oVal := oBody.GetValue('menge'); if (Assigned(oVal)) then nMenge := iVal(oVal.Value);
end;
if ((Empty(cArtikel)) or (nMenge <= 0)) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'artikel und menge sind Pflicht');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 2) Buchen. Die Transaktionssteuerung bleibt beim Skript; der
// Idempotenz-Speicher des Servers läuft getrennt davon und
// umschliesst diesen Block nicht.
cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);

// 3) Antwort vollständig aufbauen - genau sie wird eingefroren und bei
// einer Wiederholung erneut ausgeliefert.
oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('uid', cNeueUid);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Abmelden - ohne Endpunkt und ohne Skript==

Beim Abmelden soll das Gerät seine Sitzung wirklich verlieren, nicht erst mit dem
Ablauf des Tokens. Dafür ist '''nichts einzurichten''': ein ''DELETE'' auf den
JWT-Endpunkt mit dem Access-Token genügt, der Server sperrt die Sitzung in
''RESTSRV_TOKEN'' und antwortet 204.

Gesperrt wird die ganze Sitzung, also auch die Access-Token vorheriger
Erneuerungen. Ein zweiter Aufruf ist unschädlich und bleibt 204. Kann der Server
die Sitzung nicht sperren, antwortet er '''503''' mit ''Retry-After'' - die App
wiederholt den Abmeldevorgang dann.

Nur wenn beim Abmelden zusätzlich etwas passieren soll - hier: die
Geräteregistrierung für Push löschen -, braucht es einen eigenen Endpunkt. Er
erledigt seine Fachlogik und setzt ''_OBS_JWT_REVOKE'':

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cAlle: string;
begin
oRes := TJSONObject.Create();
try
PushRegistrierungLoeschen(oParams.Values['_OBS_JWT_CLAIM_technikerUid']);

// Optional: {"alleGeraete": true} meldet den Techniker ueberall ab.
// Diese Entscheidung gehoert bewusst in ein Skript - sie braucht eine
// Berechtigungspruefung, die der JWT-Endpunkt nicht leisten kann.
cAlle := 'session';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('alleGeraete');
if (Assigned(oVal)) and (Lower(oVal.Value) = 'true') then begin
cAlle := 'all';
end;
end;

oRes.AddPair('_OBS_JWT_REVOKE' , cAlle);
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"tech1\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/auth/

{"token":"eyJ...","accessToken":"eyJ...","refreshToken":"eyJ...",
"expiresIn":3600,"serverTime":"2026-06-29T15:30:12+02:00"}

Bei falschen Zugangsdaten antwortet der Server mit '''401''' und dem Text aus dem
Authenticate-Skript als ''error.message''.

Auftrag lesen (liefert den ETag-Header):

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711
... ETag: 7

ändern mit korrektem If-Match -> 200, mit veraltetem If-Match -> 409:

curl -i -X PUT -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "If-Match: 7" -H "Content-Type: application/json" ^
-d "{\"status\":\"erledigt\"}" ^
https://api.meinserver.de/orders/4711

Material idempotent erfassen (zweiter Aufruf mit gleichem Key -> gleiche Antwort, keine Doppelbuchung):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Idempotency-Key: 9c84-7f2a-..." -H "Content-Type: application/json" ^
-d "{\"artikel\":\"A100\",\"menge\":3}" ^
https://api.meinserver.de/orders/4711/material

Die Antwort des zweiten Aufrufs trägt zusätzlich den Header
''Idempotent-Replay: true'' - daran ist erkennbar, dass sie aus dem Speicher kam
und nichts erneut gebucht wurde.

Token erneuern (Refresh-Token im Authorization-Header an denselben JWT-Endpunkt):

curl -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer <refreshToken>" ^
https://api.meinserver.de/auth/

Die Antwort enthält ein neues Paar. Das alte Refresh-Token ist damit verbraucht:
ein zweiter Aufruf mit demselben Token antwortet '''401'''. Erfolgt er innerhalb
von 60 Sekunden, bleibt die Sitzung bestehen (paralleler Refresh der App); später
gilt er als Wiedervorlage und die '''ganze Sitzung wird gesperrt''' - der
Techniker muss sich neu anmelden, und der Vorfall steht mit IP im Protokoll.

Abmelden - DELETE auf denselben JWT-Endpunkt, Access-Token im Header:

curl -i -X DELETE -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/auth/

HTTP/1.1 204 No Content

Derselbe Token danach noch einmal verwendet:

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711

HTTP/1.1 401 Unauthorized

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00G9TOK09",
"message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden",
"traceId": "20260819T091233123-00001A"
}
}
</pre>

==Was zeigt das Beispiel?==

* Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422.
* Optimistic Concurrency über ''ETag'' (GET) und ''If-Match'' (PUT) -> 409 VERSION_CONFLICT.
* Idempotente Schreibzugriffe über den ''Idempotency-Key'' - '''vom Server erledigt''', das Skript enthält dafür keine Zeile Code.
* Rollenprüfung aus dem Token-Claim ''_OBS_JWT_CLAIM_roles'', nicht aus dem Body.
* JWT mit Custom-Claims (''tenant''/''roles'') und Refresh-Token mit Rotation - '''vom Server erledigt''', das Skript führt keine Sperrtabelle.
* Anmelden, Erneuern und Abmelden über '''einen''' Endpunkt - Abmelden als ''DELETE'', ohne eigene Endpunkt-Zeile und ohne Skript.
* ''_OBS_JWT_REVOKE'' für den Fall, dass beim Abmelden zusätzlich Fachlogik laufen soll oder alle Geräte gemeint sind.
* ''traceId'' im Fehler-Body für die Support-Nachverfolgung (auch als Header ''X-Trace-Id'').

OBS/Kostenpflichtige Module/RESTServer

2026-08-19T12:00:36Z

Rademacker:

{{Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

Der REST-Server ist die '''universelle Schnittstelle''' Ihrer OBS-Installation nach außen. Er macht aus Ihrem OBS einen Dienst, mit dem andere Programme - Webseiten, Apps, Geräte, Kundensysteme, Cloud-Dienste - direkt sprechen können. Statt Daten manuell zu exportieren, zu mailen oder über Umwege bereitzustellen, holen sich angebundene Systeme genau die Information, die sie brauchen, in dem Moment, in dem sie sie brauchen - oder liefern neue Daten direkt in OBS ab.

Für Anwender, die nicht selbst programmieren, bedeutet das: '''Was bisher nur manuell, per Datei-Import oder über Spezialschnittstellen ging, lässt sich jetzt automatisieren.''' Eine Webseite zeigt live aktuelle Lagerbestände. Mitarbeiter erfassen Zeiten über das Handy, ohne dass jemand Excel-Listen einpflegen muss. Ein Kunde stößt per Bestelltaste in seinem System einen Vorgang in Ihrem OBS an. Ein Lieferant meldet Wareneingänge automatisch zurück. Jeder dieser Anwendungsfälle wird einmal eingerichtet und läuft danach automatisch.

Technisch gesehen ist der REST-Server ein in OBS integrierter, voll konfigurierbarer '''HTTP/HTTPS-Dienst''', dessen Endpunkte über in OBS gepflegte Pascal-Skripte realisiert werden. Jeder Endpunkt bekommt eine eigene Adresse, eine eigene Logik und eine eigene Berechtigungsstruktur. Rückgaben erfolgen ausschliesslich im JSON-Format. Damit lassen sich beliebige Lese- und Schreibvorgänge auf der OBS-Datenbank realisieren, ohne dass externe Systeme direkten Datenbank-Zugriff erhalten - das ganze OBS-Regelwerk (Rechte, Validierung, Geschäftslogik) bleibt aktiv.

Im Ergebnis ist der REST-Server kein einzelnes Feature, sondern ein '''Werkzeugkasten''': Was an Daten oder Funktionen in OBS verfügbar ist, kann über den REST-Server auch nach außen angeboten - oder von außen entgegengenommen - werden. Die Bandbreite reicht vom einfachen Lese-Endpunkt für ein Webseiten-Widget bis hin zu kompletten B2B-Integrationen mit Mandanten- und Rollen-Trennung.

Aufruf des Moduls in OBS:
'''Stammdaten''' -> '''Z Weitere Stammdaten''' -> '''REST-Server'''

==Anwendungsbereiche==

Die folgenden Einsatzfälle sind typische Beispiele, an denen sich der praktische Nutzen ablesen lässt. Es ist keine abschliessende Liste - alles, was sich in OBS-Skripten abbilden lässt, kann auch über einen Endpunkt bereitgestellt werden.

{{Hinweis|Dies sind Beispiele. Für die konkrete Entwicklung können, je nach Komplexität, weitere Kosten anfallen.}}

===Webseiten und Kundenportale===

* '''Live-Daten auf der eigenen Webseite:''' Lagerbestände, Verfügbarkeiten, Preise, Auftragsstatus aus OBS direkt anzeigen, ohne tägliche Datei-Exports.
* '''Kundenportale:''' Kunden sehen ihre offenen Posten, Auftragshistorie, Lieferscheine. Die Seite holt sich die Daten zur Anzeigezeit direkt aus OBS, jeder Kunde sieht nur seine eigenen Daten.
* '''Trackingseiten:''' Status einer Bestellung, eines Auftrags oder einer Reparatur für Endkunden, abrufbar über eine Sendungsnummer.

===Mobile Anwendungen und Außendienst===

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''QR-/Barcode-Scanner und Lagergeräte:''' Wareneingang, Inventur, Kommissionierung direkt in OBS abbilden, ohne zwischengeschaltete Software.
* '''Außendienst-Apps:''' Techniker sehen ihre Aufträge, dokumentieren Einsätze, erfassen Material - synchronisiert mit OBS.

===Anbindung von Drittsystemen===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''Buchhaltungs- und ERP-Systeme:''' Bidirektionaler Austausch von Belegen, Stammdaten und Buchungen.
* '''CRM- und Marketing-Tools:''' Personendaten, Aktivitäten oder Mailing-Empfänger werden synchron gehalten.
* '''Logistikdienstleister:''' Versandaufträge werden übergeben, Tracking-Informationen zurückgeliefert.

===Automatisierte Rückmeldungen (WebHooks)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''Versanddienste:''' Statusmeldungen (verschickt, zugestellt, retour) werden direkt im passenden Vorgang dokumentiert.
* '''Cloud-Workflows:''' Externe Automatisierungs-Plattformen (Make, Zapier, n8n, ...) stoßen OBS-Vorgänge an oder werden von OBS aus angesprochen.

===Geschäftspartner-Kommunikation (B2B)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''Kunden-Schnittstelle:''' Grosskunden bestellen direkt aus ihrem ERP heraus, Stammdaten und Konditionen werden zentral gepflegt.
* '''Sichere Maschine-zu-Maschine-Kommunikation:''' Mit Mutual-TLS (mTLS) wird sichergestellt, dass nur die freigeschalteten Partnersysteme - und niemand sonst - mit OBS sprechen können.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''Verbindung mehrerer Standorte:''' Verteilte Systeme tauschen Daten über definierte Endpunkte aus, ohne offene Datenbankverbindungen.
* '''Datenbereitstellung für Dashboards und Auswertungen:''' BI-Tools (Power BI, Grafana, ...) lesen aufbereitete Kennzahlen direkt aus OBS.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''Fehler werden weniger.''' Jede manuelle Stelle ist eine mögliche Fehlerquelle; jede Automatisierung eine Stelle, an der nichts mehr schiefgehen kann.
* '''Neue Geschäftsmodelle werden möglich.''' Kunden- und Lieferantenportale, Self-Service-Funktionen, App-Anbindungen lassen sich aufbauen, ohne ein zweites System pflegen zu müssen.
* '''Bestehende Software bleibt verbunden.''' Statt eine vorhandene Anwendung ablösen zu müssen, kann sie über den REST-Server an OBS angedockt werden - in beiden Richtungen.
* '''Skaliert mit:''' Was klein anfängt (ein einzelner Endpunkt für eine Webseite) kann zu einer kompletten Integrations-Plattform ausgebaut werden, ohne dass die Grundlage gewechselt werden muss.

==Architektur im Überblick==

Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:

{| class="wikitable"
! Baustein !! Tabelle !! Zweck
|-
| Server || RESTSRV_SERVER || TLS-Profil + eigene HTTP-Server-Instanz, kann mehrfach existieren
|-
| Bindung || RESTSRV_BINDINGS || IP-Adresse + Port pro Server
|-
| Zugang || RESTSRV_ACCOUNT || API-Key, optionale Host- und CORS-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| Protokoll || RESTSRV_PROTO || Laufende Ereignisse, Fehler, Audit-Einträge
|-
| Statistik || RESTSRV_STATS || Aufrufzähler, Antwortzeiten und HTTP-Status pro Endpunkt
|}

Eine Anfrage durchläuft folgende Stationen:

# Rate-Limit-Prüfung (pro API-Key bzw. IP und global, Schwellen je Server-Profil)
# Authentifizierung über den API-Key (Header ''apikey'')
# CORS-Prüfung (sofern ''Origin''-Header gesetzt)
# Optional: JWT-Prüfung - Signatur, Ablauf und Sitzung (sofern für den Zugang aktiviert)
# Routing: Auflösung des Pfads über die Pfad-Templates der Endpunkte
# Prüfung der Berechtigung (Zugang -> Endpunkt)
# Idempotenz-Prüfung (nur bei POST/PUT/PATCH/DELETE '''mit''' ''Idempotency-Key''-Header)
# Ausführung des Endpunkt-Skripts (oder WebHook-Antwort)
# Festschreiben des Ergebnisses im Idempotenz-Speicher (sofern in Schritt 7 reserviert)
# JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag

==Adressierung==

Ein Endpunkt wird über ein '''Pfad-Template''' angesprochen, das den Pfad nach dem Host beschreibt und Platzhalter enthalten kann:

http://[Hostadresse][:Port][Pfad-Template]

Beispiele:

https://api.meinserver.de/kalender/v1
https://api.meinserver.de/orders/{uid}
https://api.meinserver.de/orders/{uid}/modules/{code}

Statische Segmente müssen exakt passen; Platzhalter in geschweiften Klammern (z.B. {uid}) matchen einen beliebigen Wert und stehen im Skript als Pfad-Parameter zur Verfügung. Eine Versionskennung wird als statisches Segment ins Template aufgenommen (z.B. /kalender/v1), um eine Funktionalität zu verändern, ohne bestehende Konsumenten zu brechen. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==Unterstützte HTTP-Methoden==

Der Server akzeptiert die Methoden '''GET''', '''POST''', '''PUT''', '''DELETE''' und '''PATCH''' sowie '''OPTIONS''' (CORS-Preflight, ohne Skript-Aufruf). Jede Methode wird im Endpunkt-Skript als gleichnamige Funktion implementiert. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Datei-Uploads==

Endpunkte, die dafür freigeschaltet sind (<code>re_upload</code>), nehmen Dateien
per <code>multipart/form-data</code> oder als fortsetzbaren '''Resumable-Upload'''
(<code>Content-Range</code>) entgegen. Die maximale Grösse wird pro Endpunkt
festgelegt (<code>re_upload_size</code>, Standard 25 MB); Überschreitung
ergibt 413, ein Upload an einen nicht freigeschalteten Endpunkt 415. Der Server
legt die Datei temporär ab und übergibt dem Skript den Pfad; die weitere
Verarbeitung (z.B. DMS-Ablage) übernimmt das Skript. Details:
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Doppelte Sendungen abfangen (Idempotenz)==

Ein Client, der nach einem Timeout dieselbe Anfrage erneut schickt, darf keine
Zweitbuchung auslösen. Der Server erledigt das selbst: Sendet ein Aufruf mit
'''POST''', '''PUT''', '''PATCH''' oder '''DELETE''' den Header
<code>Idempotency-Key</code>, merkt sich der Server Schlüssel und Ergebnis in
'''RESTSRV_IDEMPOTENCY'''. Eine Wiederholung mit demselben Schlüssel und demselben
Inhalt bekommt die '''gespeicherte Antwort''' zurück - das Endpunkt-Skript läuft
gar nicht erst an.

* '''Ohne den Header ändert sich nichts.''' Bestehende Endpunkte verhalten sich unverändert.
* '''Kein Schalter am Endpunkt.''' Die Mechanik greift automatisch, sobald der Header anliegt.
* '''Das Skript muss nichts tun.''' Eine eigene Idempotenz-Logik im Skript ist nicht mehr nötig.

Details und die Statuscodes: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

==Sitzungen und Abmelden==

Ein JWT trägt seine Gültigkeit in sich: der Server prüft Signatur und Ablauf und
braucht dafür keine Datenbank. Genau deshalb liesse sich ein ausgegebener Token
von sich aus auch nicht mehr zurückziehen - ein verlorenes Gerät wäre bis zum
Ablauf des Tokens weiter nutzbar.

Der Server führt deshalb zu jedem ausgestellten Token-Paar eine Zeile in
'''RESTSRV_TOKEN''' und prüft jeden Zugriff dagegen. Daraus ergeben sich drei
Eigenschaften:

* '''Abmelden wirkt sofort.''' Ein ''DELETE'' auf den JWT-Endpunkt sperrt die Sitzung; alle Token dieser Sitzung sind damit unmittelbar ungültig, auch die noch nicht abgelaufenen. Anmelden, Erneuern und Abmelden laufen also über einen einzigen Endpunkt, und für das Abmelden ist kein Skript nötig.
* '''Ein Refresh-Token gilt genau einmal.''' Beim Erneuern wird es entwertet. Wird es später erneut vorgelegt, gilt das als Diebstahl oder Fehlfunktion: die betroffene Sitzung wird komplett gesperrt und der Vorfall protokolliert.
* '''Alle Geräte abmelden.''' Ein gewöhnlicher Endpunkt kann über das Antwortfeld ''_OBS_JWT_REVOKE'' auch alle Sitzungen eines Benutzers sperren - der Support-Fall „Gerät verloren".

{{Achtung|Mit der Einführung dieser Prüfung verlieren '''alle vorher
ausgestellten Token''' ihre Gültigkeit, weil sie zu keiner Sitzung gehören.
Angemeldete Konsumenten müssen sich nach dem Update einmalig neu anmelden.}}

Der Speicher pflegt sich selbst: Zeilen werden gelöscht, sobald sowohl das
Access- als auch das Refresh-Token abgelaufen sind. Details und die Skript-Seite:
[[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Fehlerformat==

Jede Fehlerantwort des Servers hat dieselbe Form: ein einziges ''error''-Objekt
mit maschinenlesbarem Code, Support-Kennung, Meldung und Korrelations-ID:

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00E2RTPDY",
"message": "Ungültiges oder abgelaufenes Token",
"traceId": "20260817T091233123-00001A"
}
}
</pre>

* '''code''' - sprechender Bezeichner (z.B. ''AUTH_EXPIRED'', ''NOT_FOUND'', ''RATE_LIMITED'', ''INTERNAL_ERROR''), an dem ein Client seine Reaktion festmachen kann, ohne Texte auszuwerten.
* '''uid''' - OBS-Kennung der Codestelle. Für die Support-Recherche gedacht, nicht zur Auswertung im Client.
* '''message''' - Text für den Client. Interne Fehlerdetails stehen nie darin, sondern ausschliesslich im Protokoll '''RESTSRV_PROTO'''.
* '''traceId''' - Korrelations-ID. Steht zusätzlich im Header ''X-Trace-Id'' und in jeder zugehörigen Logzeile.

Ein Endpunkt-Skript kann eigene Codes setzen; siehe
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

{{Achtung|Früher standen ''Fehlercode'', ''Nachricht'' und ''traceId'' zusätzlich
flach neben dem ''error''-Objekt. Diese Felder sind entfallen - der Wert von
''Fehlercode'' heisst jetzt ''error.uid'', ''Nachricht'' entspricht
''error.message''. Clients, die die flachen Felder auswerten, müssen angepasst
werden.}}

==Sicherheitsmerkmale==

Der REST-Server enthält eine Reihe von Schutzmechanismen:

* '''Rate-Limit:''' Standardmässig max. 10 fehlgeschlagene und 120 erfolgreiche Anfragen pro API-Key (Account) bzw. IP und 60 Sekunden, max. 600 Anfragen global pro 60 Sekunden. Beim Überschreiten wird HTTP 429 mit ''Retry-After''-Header zurückgegeben. Die vier Schwellen lassen sich '''pro Server-Profil''' hinterlegen; die Zähler laufen ebenfalls getrennt je Profil, ein überlastetes Profil bremst das andere also nicht mit aus. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].
* '''Body-Limit:''' max. 10 MB Request-Body (JSON), max. 1024 Zeichen pro Header- oder Query-Parameter. Datei-Uploads laufen über einen separaten Pfad und sind pro Endpunkt auf <code>re_upload_size</code> MB begrenzt (Standard 25 MB).
* '''Sensible Felder''' (''password'', ''token'', ''secret'', ''apikey'', ''authorization'', ''cookie'', ...) werden in Protokoll-Ausgaben automatisch maskiert.
* '''Widerrufbare Token:''' Jedes ausgestellte Token-Paar gehört zu einer Sitzung in '''RESTSRV_TOKEN''' und wird bei '''jedem''' Zugriff dagegen geprüft. Eine Abmeldung wirkt damit sofort und nicht erst mit dem Ablauf des Tokens; ein Refresh-Token gilt genau einmal. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].
* '''Reserviertes Präfix:''' Parameter-Namen mit Präfix ''_OBS_'' können von aussen nicht gesetzt werden, sie sind für den Server reserviert (z.B. JWT-Claims).
* '''Geblockte Header:''' ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key'' werden nicht an das Skript durchgereicht.
* '''TLS:''' Bei Profilen mit aktivem TLS fährt der Server ohne Zertifikat und Key nicht hoch. Plain-HTTP ist nur für ein dediziertes Debug-Profil möglich.
* '''mTLS''' (Mutual TLS): erzwingt, dass jeder Client ein gültiges Client-Zertifikat vorlegt. Optional kann pro Zugang ein erwarteter Subject-DN hinterlegt werden.
* '''DNS-Cache:''' Host-zu-IP-Auflösungen für die Zugangs-Host-Prüfung werden 5 Minuten gecached.

==Protokoll==

Die Tabelle '''RESTSRV_PROTO''' enthält alle relevanten Ereignisse: erfolgreiche und abgelehnte Anfragen, TLS-/JWT-Fehler, Bindungs-Ereignisse, Skript-Fehler. Einträge sind nach Datum, Uhrzeit und Host (IP oder Account-Name) sortiert. Das Protokoll ist die erste Anlaufstelle bei Störungen. Jede Antwort trägt zudem eine Korrelations-ID (Response-Header ''X-Trace-Id''), die in den Protokoll-Einträgen wiederzufinden ist.

==Statistik==

Die Tabelle '''RESTSRV_STATS''' enthält eine Statistik aller bearbeiteten Anfragen mit Zugang, Endpunkt, Methode, HTTP-Status und Laufzeit in Millisekunden. Aufruf der Statistik:

* Aus der Endpunkt-Liste: F8 zeigt die Statistik des markierten Endpunkts.
* Aus der Zugänge-Liste: F8 zeigt die Statistik des markierten Zugangs.

==Konsole==

Wird der REST-Server nicht als Dienst, sondern interaktiv gestartet, erscheint eine farbige Konsole mit Live-Log. Die wichtigsten Befehle:

{| class="wikitable"
! Befehl !! Wirkung
|-
| ''show <n>'' || Zeigt die Details zum Debug-Eintrag ''#n'' (z.B. Request-Header, Response-Body), JSON wird farbig formatiert
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Einträge landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]] - API-Keys, JWT, CORS, Host-Beschränkung
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

OBS/Kostenpflichtige Module/RESTServer/Scripting

2026-08-19T12:00:25Z

Rademacker:

{{Kostenpflichtige Module}}

=Anleitung für Endpunkt-Skripte=

Jede Anfrage an einen Endpunkt wird nach erfolgreicher Authentifizierung und Autorisierung an das hinterlegte Skript weitergegeben. Das Skript ist in Object Pascal geschrieben und greift auf die OBS-Bibliothek (DB-Zugriff, Hilfsfunktionen) zu.

==Sicherheitshinweise==

{{Hinweis|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Übergabeparameter dürfen niemals ungeprüft in SQL-Anweisungen eingebaut werden. Werte immer über ''DB_SQLVal'' bzw. Parameter-Bindings absichern, Eingabewerte gegen Whitelists prüfen.}}

* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
* Nur das zurückgeben, was der Konsument wirklich braucht - keine internen IDs, keine Sys-Felder, keine Passwörter.
* Bei Fehlern keine internen Details an den Konsumenten zurückgeben; stattdessen schreibt der Server ohnehin Detail-Einträge in '''RESTSRV_PROTO'''.

==Methoden-Signatur==

Pro HTTP-Methode wird im Skript eine gleichnamige Funktion implementiert. Der Server ruft genau die Funktion auf, die zur Methode des eingehenden Requests passt.

function Get (oParams: TStrings; oBody: TJSONObject): string;
function Post (oParams: TStrings; oBody: TJSONObject): string;
function Put (oParams: TStrings; oBody: TJSONObject): string;
function Delete(oParams: TStrings; oBody: TJSONObject): string;
function Patch (oParams: TStrings; oBody: TJSONObject): string;

Nicht implementierte Methoden liefern automatisch ''405''-ähnliche Fehler über die generische Skript-Antwort.

==Parameter==

===oParams (TStrings)===

Enthält alle Query-Parameter, POST-Parameter (form-urlencoded) sowie die durchgereichten HTTP-Header. Werte sind immer Strings.

Filterung durch den Server:

* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
* Parameter mit Präfix '''_OBS_''' können von aussen nicht gesetzt werden; sie sind für interne Werte reserviert.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.

Zugriff im Skript:

if (not Empty(oParams.Values['kundennr'])) then begin
cKundenNr := oParams.Values['kundennr'];
end;

===oBody (TJSONObject)===

Enthält den Request-Body, sofern dieser ein gültiges JSON-Objekt ist. Bei leerem oder nicht-JSON-Body wird ''nil'' übergeben.

{{Hinweis|'''Generics funktionieren im Skript nicht.''' Aus Delphi bekannte
Schreibweisen wie ''oBody.TryGetValue<string>('feld', cVar)'' lassen sich nicht
übersetzen. Gelesen wird über ''GetValue''.}}

''GetValue'' liefert ''nil'', wenn das Feld im Body '''nicht enthalten''' ist -
daran lässt sich „nicht gesendet" von „leer gesendet" unterscheiden. Der Wert ist
immer ein '''String''' und wird bei Bedarf selbst gewandelt.

cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username');
if (Assigned(oVal)) then begin
cUser := oVal.Value;
end;
oVal := oBody.GetValue('password');
if (Assigned(oVal)) then begin
cPass := oVal.Value;
end;
end;

Bei mehr als zwei Feldern lohnt eine kleine Hilfsfunktion, die das Muster einmal
kapselt:

<syntaxhighlight lang="pascal" line>
function _BodyStr(oBody: TJSONObject; const cFeld: string): string;
var oVal: TJSONValue;
begin
result := '';
if (oBody = nil) then begin
exit;
end;
oVal := oBody.GetValue(cFeld);
if (Assigned(oVal)) then begin
result := oVal.Value;
end;
end;

// Aufruf:
cBetreff := _BodyStr(oBody, 'betreff');
</syntaxhighlight>

Andere Typen entstehen aus dem String:

{| class="wikitable"
! Zieltyp !! Umwandlung
|-
| Ganzzahl || <code>iVal(_BodyStr(oBody, 'menge'))</code>
|-
| Kommazahl || <code>fVal(StrTran(_BodyStr(oBody, 'preis'), '.', ','))</code> - '''JSON liefert den Dezimalpunkt''', ''fVal'' erwartet die lokale Notation
|-
| Boolean || <code>Lower(_BodyStr(oBody, 'aktiv')) = 'true'</code>
|-
| Datum/Zeit || ISO-8601-String selbst zerlegen (''CToDT'' erwartet das deutsche Format)
|}

Maximale Body-Grösse: 10 MB.

===Reservierte _OBS_-Parameter===

Bei aktiver JWT-Authentifizierung stehen die Token-Claims als Parameter zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_JWT_ID || JWT-Id (''jti''-Claim) - typisch die User-Id. '''Muss nicht eindeutig sein''': die Sitzung führt der Server über eigene Kennungen (siehe unten)
|-
| _OBS_JWT_SUBJECT || Subject (''sub''-Claim) - typisch Benutzername
|-
| _OBS_JWT_AUDIENCE || Audience (''aud''-Claim) - typisch Mandant / Rolle
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim des Tokens (z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles); im Folge-Skript lesbar
|-
| _OBS_TRACE_ID || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}

Unabhängig von JWT stehen ausserdem immer zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_SERVER_TIME || Aktuelle Serverzeit als ISO-8601 '''mit UTC-Offset''' (z.B. ''2026-08-17T09:12:33+02:00''). Nützlich, um Datumswerte in derselben Zeitzone auszuliefern, in der der Server arbeitet, und damit ein Client seinen Uhren-Versatz bestimmen kann
|-
| _OBS_JWT_EXP_SEC || Laufzeit des Access-Tokens in Sekunden (''JWT-Exp'' × 60). Damit kann ein Konfigurations-Endpunkt denselben Wert ausliefern, den der Token wirklich hat
|}

Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.

Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
''_OBS_JWT_CLAIM_sid'' und ''_OBS_JWT_CLAIM_rid'':

{| class="wikitable"
! Claim !! Inhalt
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
|}

Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Skripts gesetzt - ein Skript kann sie also auch mit ''_OBS_JWT_CLAIM_sid'' nicht
überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.

===Pfad-Parameter===

Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte als reservierte Parameter mit Präfix '''_OBS_PATH_''' in ''oParams'' bereit:

{| class="wikitable"
! Template !! Zugriff im Skript
|-
| <code>/orders/{uid}</code> || ''oParams.Values['_OBS_PATH_uid']''
|-
| <code>/orders/{uid}/modules/{code}</code> || ''oParams.Values['_OBS_PATH_uid']'', ''oParams.Values['_OBS_PATH_code']''
|}

Da der Präfix ''_OBS_'' für von aussen gelieferte Header- und Query-Parameter gesperrt ist, sind diese Werte nicht durch den Client fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].

===Datei-Uploads===

Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), nimmt der Server
hochgeladene Dateien entgegen, legt sie in einem temporären Verzeichnis ab und
übergibt dem Skript Pfad, Originalname und Content-Type über reservierte
Parameter. Das Skript entscheidet selbst über die weitere Verarbeitung (z.B.
DMS-Ablage). Der Body wird in diesem Fall '''nicht''' als JSON geparst - ''oBody''
ist ''nil''. Es gilt nicht das JSON-Body-Limit (10 MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25 MB;
Überschreitung -> 413).

Beide Übertragungsarten - <code>multipart/form-data</code> und der resumable
<code>Content-Range</code>-Upload - liefern dem Skript dieselben Parameter:

{| class="wikitable"
! Parameter !! Inhalt
|-
| _OBS_UPLOAD_PATH || Vollständiger Pfad zur temporären Datei auf dem Server
|-
| _OBS_UPLOAD_NAME || Originaldateiname
|-
| _OBS_UPLOAD_CONTENTTYPE || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt)
|}

Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''_OBS_UPLOAD_PATH'' und ''_OBS_UPLOAD_NAME''
gesetzt sind, sobald es läuft.

{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}

====Einfacher Upload (multipart/form-data)====

Eine Datei pro Request. Name und Content-Type stammen aus der
<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
Server speichert die erste Datei-Partie und ruft das Skript auf:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cPfad: string;
cName: string;
cTyp : string;
begin
oRes := TJSONObject.Create();
try
cPfad := oParams.Values['_OBS_UPLOAD_PATH'];
cName := oParams.Values['_OBS_UPLOAD_NAME'];
cTyp := oParams.Values['_OBS_UPLOAD_CONTENTTYPE'];

// ... Datei aus cPfad ins DMS / Zielverzeichnis uebernehmen ...

oRes.AddPair('status' , 'ok');
oRes.AddPair('dateiname', cName);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

====Resumable/Chunked Upload (Content-Range)====

Für grosse Dateien überträgt der Client die Datei in Teilstücken (Chunks) mit dem
Header <code>Content-Range: bytes START-END/TOTAL</code>. Der Server hängt die
Chunks '''sequentiell''' an eine Session-Datei an und behandelt unvollständige
Uploads selbst - das Endpunkt-Skript läuft '''erst beim vollständigen Upload'''
(dann mit gesetztem ''_OBS_UPLOAD_PATH'', ''_OBS_UPLOAD_NAME'' und
''_OBS_UPLOAD_CONTENTTYPE'').

Name und Content-Type sind im <code>Content-Range</code>-Protokoll nicht enthalten;
der Client liefert sie deshalb '''im ersten Chunk''' über den Header
<code>Upload-Metadata</code> (Format wie bei tus: kommagetrennte Paare
<code>schlüssel base64wert</code>, Werte Base64-kodiert):

<pre>
Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm
</pre>

Erkannt werden die Schlüssel <code>filename</code> (Pflicht) und
<code>filetype</code> (optional). Fehlt <code>filename</code> im ersten Chunk,
wird der Upload mit '''400''' abgelehnt, ohne dass eine Datei angelegt wird.
Folge-Chunks und Statusabfragen müssen die Metadaten nicht erneut senden.

Ablauf (vom Client gesteuert, der Server antwortet jeweils):

{| class="wikitable"
! Request !! Server-Antwort
|-
| Erster Chunk <code>Content-Range: bytes 0-1048575/5000000</code> + <code>Upload-Metadata</code> || '''308''' Resume Incomplete + Header <code>Upload-Id</code>, <code>Upload-Offset</code>, <code>Range</code>
|-
| weitere Chunks (jeweils <code>Upload-Id</code> mitsenden) || '''308''' mit aktualisiertem <code>Upload-Offset</code>
|-
| letzter Chunk (Bereich erreicht TOTAL) || normale Skript-Antwort (z.B. '''200'''/'''201''')
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> || aktueller <code>Upload-Offset</code>, ohne anzuhängen (Resume)
|}

{| class="wikitable"
! Header !! Richtung !! Bedeutung
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
|-
| Upload-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
|-
| Upload-Id || Request/Response || Session-Kennung. Fehlt sie im ersten Request, erzeugt der Server eine und gibt sie zurück; alle Folge-Chunks müssen sie mitsenden.
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
|}

Der Server hängt einen Chunk '''nur an, wenn START dem bereits gespeicherten Stand
entspricht'''. Bei Abweichung (doppelter Chunk, Lücke) wird nicht angehängt,
sondern der aktuelle ''Upload-Offset'' zurückgemeldet - der Client setzt ab dort
neu auf. Eine separate Statusabfrage ist für ein Resume daher nicht zwingend nötig.

Überschreitet ein Chunk bzw. die Gesamtgrösse das Limit (''re_upload_size''),
antwortet der Server mit '''413 Payload Too Large'''.

{{Hinweis|Der Upload-Status liegt prozesslokal im Speicher. Nach einem Neustart des Servers muss ein unvollständiger Upload neu begonnen werden.}}

==Rückgabe==

Die Rückgabe ist immer ein '''JSON-String'''. Wird ein leerer String zurückgegeben, antwortet der Server automatisch mit ''{}''. Der Server setzt Content-Type auf ''application/json; charset=utf-8'' und Status auf 200, sofern das Skript nicht selbst einen Fehler signalisiert.

Einfaches Beispiel:

<syntaxhighlight lang="pascal" line>
function Get(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
oRes := TJSONObject.Create();
try
oRes.AddPair('wert_string', '123');
oRes.AddPair('wert_int' , 456);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Antwort steuern: Statuscode, Header, traceId==

Ein Skript kann den HTTP-Statuscode und beliebige Response-Header über reservierte Felder in der Antwort setzen. Der Server wertet sie aus und entfernt sie vor dem Senden aus dem Body.

{| class="wikitable"
! Antwort-Feld !! Wirkung
|-
| _OBS_HTTP_STATUS (Zahl) || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200. Bei 204 wird kein Body gesendet.
|-
| _OBS_HEADERS (Objekt) || Beliebige Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen/Werten werden entfernt (Schutz vor Header-Injection).
|-
| _OBS_JWT_REVOKE (Text) || Sperrt die Sitzung des vorgelegten Tokens (''session'') oder alle Sitzungen des Subjects (''all''). Damit wird ein Endpunkt zum Logout, ohne eigene Verwaltung. Scheitert das Sperren, antwortet der Server mit '''503''' statt mit der Antwort des Skripts - siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Abschnitt Abmelden.
|}

Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oParams.Values['_OBS_TRACE_ID']'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

===Beispiel: Anlegen mit 201, Location und ETag===

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
// ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...
oHdr := TJSONObject.Create();
oHdr.AddPair('Location', '/v1/orders/' + cNeueUid);
oHdr.AddPair('ETag', '1');

oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('uid', cNeueUid);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Beispiel: Strukturierter Fehler mit Statuscode und traceId===

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
oErr := TJSONObject.Create();
oErr.AddPair('code', 'VALIDATION_FAILED');
oErr.AddPair('message', 'Feld "menge" fehlt');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Beispiel: Optimistic Concurrency (ETag / If-Match)===

Mit Statuscode, Headern und dem lesbaren Header ''If-Match'' führt das Skript je Datensatz einen Versionszähler und lehnt veraltete Schreibzugriffe mit 409 ab:

<syntaxhighlight lang="pascal" line>
function Put(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
nAktuell, nIfMatch: integer;
begin
oRes := TJSONObject.Create();
try
nAktuell := AuftragVersion(oParams.Values['_OBS_PATH_uid']);
nIfMatch := iVal(oParams.Values['if-match']);

if (nIfMatch <> nAktuell) then begin
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell));
oRes.AddPair('_OBS_HTTP_STATUS', 409);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'VERSION_CONFLICT'));
result := oRes.ToJSON();
exit;
end;

// ... speichern, Version hochzählen ...
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell + 1));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Idempotenz - was das Skript beachten muss==

Sendet ein Konsument bei ''POST''/''PUT''/''PATCH''/''DELETE'' den Header
<code>Idempotency-Key</code>, fängt der '''Server''' doppelte Sendungen ab. Das
Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine
Prüfung am Anfang der Methode.

Was das Skript wissen muss:

{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
|-
| '''2xx''' || Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
|-
| '''5xx''' oder Exception || Der Schlüssel bleibt belegt, der Fall wird protokolliert. Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist
|}

Daraus folgen zwei Regeln für Endpunkt-Skripte:

* '''Fachliche Ablehnungen als 4xx melden''' (422, 409, 404), nicht als 2xx mit Fehlertext im Body. Sonst wird die Ablehnung gespeichert und der Konsument bekommt sie bei jedem weiteren Versuch erneut - auch nachdem er den Fehler behoben hat.
* '''Die Antwort muss vollständig sein.''' Was zurückgegeben wird, wird eingefroren. Ein Feld, das erst der zweite Aufruf ergänzen würde, kommt beim Konsumenten nie an.

{{Hinweis|Vor dieser Server-Funktion mussten Skripte die Idempotenz selbst
abbilden. Solche Skripte laufen unverändert weiter - die Doppelprüfung schadet
nicht, ist aber überflüssig und kann beim nächsten Überarbeiten entfallen.}}

Der vollständige Ablauf und die Statuscodes stehen unter
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==JWT-Authentifizierungs-Skript==

Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser : string;
cPass : string;
begin
oRes := TJSONObject.Create();
try
// Eingangsdaten lesen (Body oder Query-Param)
cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username');
if (Assigned(oVal)) then begin
cUser := oVal.Value;
end;
oVal := oBody.GetValue('password');
if (Assigned(oVal)) then begin
cPass := oVal.Value;
end;
end;

// Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
if (PasswortPasst(cUser, cPass)) then begin
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT', cUser);
oRes.AddPair('_OBS_JWT_AUDIENCE', 'mandant1');
end else begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Login fehlgeschlagen');
end;

result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

Rückgabewerte:

{| class="wikitable"
! status !! Bedeutung
|-
| 1 || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
|-
| 9 || Misserfolg, der Server antwortet mit '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
|}

{{Hinweis|Der Text aus ''error'' geht bei ''status'' = 9 '''an den Konsumenten'''
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Endanwender verständlich sein und keine internen Details verraten.}}

Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
„Passwort falsch" erscheinen.

Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.

===Aufbau der Token-Antwort===

Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
Feldern, die das Skript zurückgibt''':

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...",
"accessToken": "eyJ...",
"refreshToken":"eyJ...",
"expiresIn": 28800,
"serverTime": "2026-08-17T09:12:33+02:00"}

{| class="wikitable"
! Feld !! Herkunft
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
|-
| serverTime || Serverzeit ISO-8601 mit Offset
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
|}

Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.

===Custom-Claims, serverTime und Refresh===

Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:

{| class="wikitable"
! RÜckgabefeld !! Bedeutung
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als oParams.Values['_OBS_JWT_CLAIM_<name>'].
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
|}

Jedes Token trägt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh'') sowie die Sitzungskennungen ''sid'' und ''rid'' des Servers. Die Antwort enthält bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusätzlich ''refreshToken'':

{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}

{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''_OBS_JWT_CLAIM_*''), nie aus Body oder Query.}}

====Refresh-Methode====

Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
(Signatur, Ablauf, ''token_use=refresh'') und in der Sitzung '''entwertet'''.
Einmalgebrauch, Rotation und Sperrliste sind damit Sache des Servers. Das Skript
liefert nur noch die aktuellen Claims - genau das ist der Sinn des Aufrufs: eine
zwischenzeitlich geänderte Rolle oder ein gewechselter Mandant wirken spätestens
mit der nächsten Erneuerung.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal - einmal im Skript, einmal im
Server - und riskiert, dass beide Seiten unterschiedlicher Meinung sind. Der
Server sieht die Skript-Tabelle nicht, und das Skript sieht die Sitzung nicht.}}

Ein bereits benutztes Refresh-Token wird mit '''401''' abgelehnt. Erfolgt die
erneute Vorlage innerhalb von 60 Sekunden, bleibt die Sitzung bestehen (paralleler
Refresh einer App); danach gilt sie als Wiedervorlage und die '''gesamte Sitzung
wird gesperrt'''. Details in [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

Das alte Refresh-jti steht weiterhin als ''oParams.Values['_OBS_JWT_ID']'' bereit,
falls das Skript es für eigene Protokollierung braucht.

<syntaxhighlight lang="pascal" line>
function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cUser: string;
begin
oRes := TJSONObject.Create();
try
cUser := oParams.Values['_OBS_JWT_SUBJECT'];

// Der Server hat das vorgelegte Refresh-Token bereits geprueft und
// entwertet. Hier wird nur entschieden, ob der Benutzer die Sitzung
// fortsetzen darf - und mit welchen Rechten.
if (not BenutzerAktiv(cUser)) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
result := oRes.ToJSON();
exit;
end;

// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das neue Refresh-Token aus
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

===Abmelden (Logout)===

'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Phase 4.

Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
'''gewöhnlichen Endpunkt''' und setzt dort ''_OBS_JWT_REVOKE''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
oRes := TJSONObject.Create();
try
GeraeteRegistrierungLoeschen(oParams.Values['_OBS_JWT_SUBJECT']);

// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
oRes.AddPair('_OBS_JWT_REVOKE' , 'session');
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
abgemeldet, während sein Token weiterläuft.

==Fehlerbehandlung im Skript==

Tritt im Skript eine Exception auf oder schlägt die Syntax-Prüfung fehl, antwortet der Server mit 500 ''Interner Fehler'' und protokolliert die Detail-Meldung in '''RESTSRV_PROTO''' (mit Skript-Fehlertext). Der Konsument sieht keine internen Details.

Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Will das Skript einen spezifischen Fehler an den Konsumenten zurückgeben, sollte es
'''dasselbe Format und einen passenden Statuscode''' verwenden:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
begin
oRes := TJSONObject.Create();
try
if (Empty(oParams.Values['kundennr'])) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'Parameter ''kundennr'' fehlt');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;
// ...
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
Body auszuwerten - und nur so gibt der Server einen belegten
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}

Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.

==Gemeinsamen Code auslagern==

Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:

<pre>
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</pre>

{| class="wikitable"
! Attribut !! Bedeutung
|-
| '''T''' || Tabelle, aus der geladen wird
|-
| '''I''' || Spalte, über die gesucht wird
|-
| '''V''' || Wert, der in dieser Spalte stehen muss
|-
| '''F''' || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}

Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Compiler sieht danach den zusammengesetzten Text - eine Funktion aus der Lib lässt
sich also aufrufen wie eine im Skript selbst geschriebene.

===Bewährtes Muster: Lib als eigene Endpunkt-Zeile===

Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
RESTSRV_ENDPOINTS''' abzulegen:

# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
# Den Lib-Quelltext ins Skript-Feld dieser Zeile schreiben (F7).
# '''Keine Berechtigung''' in der Berechtigungs-Liste vergeben - das ist der Schutz: ohne Berechtigung beantwortet der Server einen Aufruf mit 403.
# In jedem nutzenden Endpunkt die Direktive oben einfügen.

Damit ist die Lib reiner Ablageort und von aussen nicht nutzbar. Eine Änderung
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
angefasst werden muss.

{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Funktion hinzu, genügt es nicht, nur das nutzende Skript zu aktualisieren. Eine
ältere Lib lädt fehlerfrei - der Compiler meldet dann ausschliesslich die neuen
Namen als ''Unknown name'', was leicht wie ein Fehler im Skript aussieht.}}

{{Hinweis|Auch hier greift der Endpunkt-Cache: eine Änderung an der Lib wird erst
nach Ablauf des TTL (bis zu 60 Sekunden) wirksam.}}

==Fallstricke im Skript==

Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:

{| class="wikitable"
! Stolperstein !! Richtig
|-
| ''DB_SOpen('Y00…', oDB, …)'' - der AD-UID-Parameter aus dem Delphi-Code || Im Skript '''ohne UID''': <code>DB_SOpen(oDB, cSql, q)</code>. Gleiches gilt für <code>qSqlInit(oDB, 'tab')</code> und <code>qSqlRead(oDB, 'tab', cWhere)</code> - jede dieser Funktionen beginnt mit ''oDB''
|-
| ''oBody.TryGetValue<T>(…)'' || Generics gibt es nicht - über ''GetValue'' lesen (siehe oBody)
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'|' + wert + '|'</code>) und mit ''Pos'' prüfen
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
|}

==Skript-Cache==

Der Server cached das kompilierte Skript pro Endpunkt (Schlüssel: ''sys_date'' des Endpunkts). Zusätzlich werden die Endpunkt-Definitionen pro Server-Profil in einem TTL-Cache (Standard 60 s) gehalten. Eine Skript-Änderung über F7 wird daher erst nach Ablauf dieses TTL (bzw. nach einer Cache-Invalidierung) wirksam - typischerweise innerhalb einer Minute, nicht zwingend sofort.

==Verfügbare Bibliotheken==

Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:

* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
* ''Base.qSqlReg'' - Schreibzugriffe
* ''System.JSON'' - JSON-Objekte und -Arrays
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''

Die wichtigsten Aufrufe mit ihren Skript-Signaturen:

{| class="wikitable"
! Zweck !! Aufruf
|-
| Lesen || <code>DB_SOpen(oDB, cSql, q)</code>, dann <code>q.EoF</code>, <code>q.Next()</code>, <code>q.A2C('feld')</code> / <code>A2I</code> / <code>A2F</code> / <code>A2D</code> / <code>A2UID()</code>, am Ende <code>DB_Close(q)</code>
|-
| Neu anlegen || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('feld', wert)</code>, <code>q.SaveData(NEW_RECORD)</code>, <code>qSqlFree(q)</code>
|-
| Ändern || <code>q := qSqlRead(oDB, 'tab', cWhere)</code>, <code>q.qSet(…)</code>, <code>q.SaveData(UPDATE_RECORD)</code>, <code>qSqlFree(q)</code>
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
|-
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
|}

{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
Skript nicht übersetzen.}}

Konkrete Beispiele:

* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

OBS/Kostenpflichtige Module/RESTServer/Zugaenge

2026-08-19T12:00:08Z

Rademacker:

{{Kostenpflichtige Module}}

=Zugänge=

Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''

==Felder==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Name || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
| CORS-Origins || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt
|-
| mTLS-Subject || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
|-
| JWT || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
| JWT-Endpunkt || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
|-
| JWT-Key || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
| JWT-Exp || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
|}

==API-Key==

Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:

apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12

Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.

{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}

==Host-Beschränkung==

Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.

==CORS==

Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.

Format der Liste:

https://app.kunde.de;https://test.kunde.de;https://localhost:8080

Ablauf:

# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste aller Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste des aktuell verwendeten Zugangs geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.

Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH''. Erlaubte Header: ''Content-Type, apikey, Authorization, Accept''. Diese Werte sind systemseitig festgelegt und werden in der Preflight-Antwort zurückgegeben.

==JWT-Authentifizierung==

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).

'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.

Unterschieden wird nach Verb und Token-Art:

{| class="wikitable"
! Aufruf !! Ablauf
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
|}

{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}

===Phase 1: Token-Bezug===

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Body: {"username":"...", "password":"..."}

Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Funktion ''Authenticate'' bereitstellen, die ein JSON-Objekt mit:

* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_<name>'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)

zurückliefert. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 28800,
"serverTime": "2026-06-29T15:30:12+02:00"}

Zum Aufbau der Antwort:

* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.

Beispiel mit Zusatzfeldern aus dem Skript:

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
"expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}

Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.

Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''' und reicht den Text aus dem Feld ''error'' als
''error.message'' an den Client durch - der Konsument kann ihn also direkt
anzeigen. Die Formulierung liegt damit beim Skript.

{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}

===Phase 2: Token-Verwendung===

Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:

GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi...

Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.

Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.

{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}

===Phase 3: Token erneuern (Refresh)===

Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Refresh-Token)

Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}

Verhalten bei einem bereits benutzten Refresh-Token:

{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
|}

Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

===Phase 4: Abmelden (Logout)===

Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
Access-Token im ''Authorization''-Header:

DELETE https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Access-Token)

HTTP/1.1 204 No Content

Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.

* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.

====Alle Geräte abmelden====

Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
Antwortfeld ''_OBS_JWT_REVOKE'', das jeder gewöhnliche Endpunkt setzen kann:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
oRes := TJSONObject.Create();
try
// 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
oRes.AddPair('_OBS_JWT_REVOKE' , 'all');
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}

==Sitzungen (RESTSRV_TOKEN)==

Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt".

* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.

==mTLS-Subject-Prüfung==

Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.

Beispiele für Subject-Strings im Cert (OneLine-DN):

/C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
/C=DE/O=Kunde GmbH/CN=client-test.kunde.de

Mit '''CN=client-prod.kunde.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Kunde GmbH;CN=client-prod.kunde.de''.

==Listen-Funktionen==

In der Zugänge-Liste (allein):

* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang

Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):

* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

OBS/Kostenpflichtige Module/RESTServer/Beispiel1

2026-08-19T10:18:04Z

Rademacker: /* JWT-Authentifizierungs-Skript (Zugang) */

{{Kostenpflichtige Module}}

=Beispiel 1: Daten-Abruf mit JWT-Authentifizierung=

In diesem Beispiel werden Steuerungs-Variablen aus OBS abgerufen und auf einer Webseite ausgegeben. Der Zugang ist mit JWT-Pflicht eingerichtet, der Konsument muss sich daher zuerst anmelden und einen Token bezogen haben.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' mit Bindung 0.0.0.0:443
* '''Zugang:''' ''Web-Dashboard''
** API-Key: zufaellig generiert
** JWT aktiv, JWT-Endpunkt ''oauth'', JWT-Key zufaellig, JWT-Exp 60 (Minuten)
** CORS-Origins: ''https://dashboard.kunde.de''
* '''Endpunkt:''' ''steuerung/v1'', dem Profil ''Public-API'' zugeordnet
* '''Berechtigung:''' Zugang ''Web-Dashboard'' fuer Endpunkt ''steuerung/v1'' freigeschaltet

==JWT-Authentifizierungs-Skript (Zugang)==

Wird ueber die Zugaenge-Liste mit '''F7''' geoeffnet. Pruefen, ob Benutzername/Passwort gegen die OBS-Benutzerverwaltung passen.

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser : string;
cPass : string;
cSql : string;
qUser : TxFQuery;
lOk : Boolean;
begin
oRes := TJSONObject.Create();
try
cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username');
if (Assigned(oVal)) then begin
cUser := oVal.Value;
end;
oVal := oBody.GetValue('password');
if (Assigned(oVal)) then begin
cPass := oVal.Value;
end;
end;

cSql := 'SELECT u_nr, u_name FROM benutzer' +
' WHERE u_login = ' + DB_SQLVal(cUser) +
' AND u_passwort_hash = ' + DB_SQLVal(HashPasswort(cPass)) +
' AND u_aktiv = ' + DB_SQLVal('1');

// DB_SOpen liefert true, wenn die ABFRAGE lief - nicht, wenn ein
// Datensatz gefunden wurde. Ohne die EoF-Pruefung wuerde jede
// Anmeldung gelingen, sobald das SQL fehlerfrei ist.
lOk := false;
if (DB_SOpen(oDB, cSql, qUser)) then begin
if (not qUser.EoF) then begin
lOk := true;
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , qUser.A2C('u_nr'));
oRes.AddPair('_OBS_JWT_SUBJECT' , qUser.A2C('u_name'));
oRes.AddPair('_OBS_JWT_AUDIENCE', 'dashboard');
end;
end;
DB_Close(qUser);

if (not lOk) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Benutzer oder Passwort ist falsch');
end;

result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|Hier steht in ''_OBS_JWT_ID'' die Benutzernummer - derselbe Wert also bei
jeder Anmeldung desselben Benutzers. Das ist zulässig: der Server führt seine
Sitzungen über eigene Kennungen (''sid''/''rid''), nicht über das ''jti'' des
Skripts. Mehrfache und parallele Anmeldungen eines Benutzers sind damit
unproblematisch.}}

==Endpunkt-Skript ''steuerung/v1''==

Liefert eine Liste von Steuerungs-Werten zurueck. Die Auswertung der JWT-Claims sorgt dafuer, dass nur Audience ''dashboard'' Daten erhaelt.

<syntaxhighlight lang="pascal" line>
procedure _AddVar(oArr: TJSONArray; const cVar: string);
var oWert : TJSONObject;
cTitel : string;
cData : string;
cEinh : string;
lString: Boolean;
lAlign : Boolean;
begin
if (ST_Variable(oDB, cVar, cTitel, cData, cEinh, lString, lAlign)) then begin
oWert := TJSONObject.Create();
oWert.AddPair('variable', cVar);
oWert.AddPair('titel' , cTitel);
oWert.AddPair('wert' , cData);
oWert.AddPair('einheit' , cEinh);
oArr.Add(oWert);
end;
end;

//------------------------------------------------------------------------------

//------------------------------------------------------------------------------
// Hilfsfunktion: Fehlerantwort im einheitlichen Format aufbauen.
// Fachliche Ablehnungen als 4xx melden, nicht als 200 mit Fehlertext.
//------------------------------------------------------------------------------

function _Fehler(oParams: TStrings; nStatus: integer; const cCode, cMsg: string): string;
var oRes: TJSONObject;
oErr: TJSONObject;
begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , cCode);
oErr.AddPair('message', cMsg);
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes := TJSONObject.Create();
try
oRes.AddPair('_OBS_HTTP_STATUS', nStatus);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

function Get(oParams: TStrings; oBody: TJSONObject): string;
var oArr: TJSONArray;
begin
// Audience-Pruefung: nur Dashboard-Tokens akzeptieren
if (oParams.Values['_OBS_JWT_AUDIENCE'] <> 'dashboard') then begin
result := _Fehler(oParams, 403, 'FORBIDDEN_ROLE', 'Token nicht für diese Anwendung ausgestellt');
exit;
end;

oArr := TJSONArray.Create();
try
_AddVar(oArr, 'WERT_1');
_AddVar(oArr, 'WERT_2');
_AddVar(oArr, 'WERT_3');
_AddVar(oArr, 'WERT_4');
result := oArr.ToJSON();
finally
MyFreeAndNil(oArr);
end;
end;
</syntaxhighlight>

==JavaScript-Client (Browser)==

Im Browser werden zwei Aufrufe gemacht: erst Token holen, dann Daten lesen.

<syntaxhighlight lang="javascript" line>
const API_BASE = 'https://api.meinserver.de';
const API_KEY = '[API-KEY]';

async function login(username, password) {
const res = await fetch(`${API_BASE}/oauth/`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'apikey': API_KEY },
body: JSON.stringify({ username, password })
});
if (!res.ok) throw new Error('Login fehlgeschlagen');
const data = await res.json();
return data.token;
}

async function ladeSteuerung(token) {
const res = await fetch(`${API_BASE}/steuerung/v1`, {
method: 'GET',
headers: {
'apikey': API_KEY,
'Authorization': 'Bearer ' + token
}
});
if (!res.ok) throw new Error('Abruf fehlgeschlagen: ' + res.status);
return res.json();
}

async function zeigeTabelle() {
const token = await login('mitarbeiter', 'geheim');
const werte = await ladeSteuerung(token);

const tbl = document.getElementById('steuerung');
werte.forEach(w => {
const tr = document.createElement('tr');
tr.innerHTML = `<td>${w.titel}</td><td>${w.wert} ${w.einheit}</td>`;
tbl.appendChild(tr);
});
}

zeigeTabelle();
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"mitarbeiter\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/oauth/

Antwort:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 3600,
"serverTime": "2026-08-19T09:12:33+02:00"}

Da das Skript kein ''_OBS_JWT_REFRESH_ID'' liefert, enthält die Antwort kein
''refreshToken'' - der Client meldet sich nach Ablauf der 60 Minuten neu an.

Daten abrufen:

curl -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJhbGciOi..." ^
https://api.meinserver.de/steuerung/v1

==Was zeigt das Beispiel?==

* Zweistufige Anmeldung: API-Key + JWT.
* Sichere Trennung von Konsumenten-Gruppen ueber die Audience-Claim.
* Eigenes Authentifizierungs-Skript pro Zugang.
* Browser-Zugriff ueber CORS-erlaubtes Origin.
* Anmeldung ohne Refresh-Token: einfachster Fall, der Token laeuft nach der Zeit aus ''JWT-Exp'' ab.

OBS/Kostenpflichtige Module/RESTServer/Beispiel5

2026-08-19T10:16:05Z

Rademacker: /* JWT-Authentifizierungs-Skript (Zugang) */

{{Kostenpflichtige Module}}

=Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz=

Dieses Beispiel zeigt einen schreibenden Endpunkt für eine mobile App: Aufträge werden mit echten HTTP-Statuscodes aktualisiert, konkurrierende Änderungen über ETag/If-Match abgesichert (Optimistic Concurrency) und doppelte Sendungen über einen Idempotency-Key abgefangen. Die Anmeldung nutzt JWT mit Custom-Claims (Mandant, Rollen) und einem Refresh-Token.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App''
** API-Key: zufällig generiert
** JWT aktiv, JWT-Endpunkt ''auth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
* '''Endpunkte''' (alle dem Profil ''Public-API'' zugeordnet):
** ''orders/{uid}'' - Auftrag lesen/Ändern
** ''orders/{uid}/material'' - Material erfassen
** ''auth/logout'' - Abmelden
* '''Berechtigung:''' Zugang ''Mobile-App'' für alle drei Endpunkte freigeschaltet

==JWT-Authentifizierungs-Skript (Zugang)==

Stellt Mandant und Rollen als Custom-Claims aus und löst über ''_OBS_JWT_REFRESH_ID'' ein Refresh-Token aus. Bei einem Refresh ruft der Server im selben Skript die Methode ''Refresh'' auf. Die Hilfsfunktionen (''PasswortPasst'', ''TechnikerMandant'', ''TechnikerRollen'') sind illustrativ und projektabhängig.

{{Hinweis|Eine '''eigene Sperrtabelle für Refresh-jti ist nicht nötig'''.
Einmalgebrauch, Rotation und Widerruf führt der Server in ''RESTSRV_TOKEN'' -
das Skript entscheidet nur, '''ob''' und '''mit welchen Rechten''' die Sitzung
fortgesetzt wird. Frühere Fassungen dieses Beispiels zeigten eine Skript-Tabelle;
wer sie übernommen hat, kann sie entfernen.}}

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser, cPass: string;
begin
oRes := TJSONObject.Create();
try
cUser := ''; cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username'); if (Assigned(oVal)) then cUser := oVal.Value;
oVal := oBody.GetValue('password'); if (Assigned(oVal)) then cPass := oVal.Value;
end;

if (PasswortPasst(cUser, cPass)) then begin
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser)); // z.B. "tech,lead"
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das Refresh-Token aus
// _OBS_JWT_REFRESH_EXP weggelassen -> Default 90 Tage
end else begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Login fehlgeschlagen');
end;
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------

function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cUser: string;
begin
oRes := TJSONObject.Create();
try

cUser := oParams.Values['_OBS_JWT_SUBJECT'];

// Das vorgelegte Refresh-Token hat der Server bereits geprueft und
// entwertet. Hier wird nur entschieden, ob die Sitzung fortgesetzt
// werden darf - und mit welchen Rechten.
if (not TechnikerAktiv(cUser)) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
result := oRes.ToJSON();
exit;
end;

// Mandant und Rollen NEU lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.

oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID());
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}'' - ändern mit ETag / If-Match==

''GET'' liefert den Auftrag samt ''ETag'' (Version), ''PUT'' prüft Rolle und ''If-Match''.

<syntaxhighlight lang="pascal" line>
function Get(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
cUid: string;
nVer: integer;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];
if (not AuftragLesen(oParams.Values['_OBS_JWT_CLAIM_tenant'], cUid, oRes, nVer)) then begin
oRes.AddPair('_OBS_HTTP_STATUS', 404);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'NOT_FOUND'));
result := oRes.ToJSON();
exit;
end;
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nVer));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------

function Put(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
cUid: string;
nAktuell, nIfMatch: integer;
begin
oRes := TJSONObject.Create();
try
// nur Rolle "lead" darf ändern - Rolle kommt aus dem Token, nicht aus dem Body.
// Mit Trennzeichen suchen: ein blosses Pos('lead', ...) wuerde auch in
// "leadless" oder "teamlead" treffen.
if (Pos(',lead,', ',' + oParams.Values['_OBS_JWT_CLAIM_roles'] + ',') = 0) then begin
oRes.AddPair('_OBS_HTTP_STATUS', 403);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'FORBIDDEN_ROLE'));
result := oRes.ToJSON();
exit;
end;

cUid := oParams.Values['_OBS_PATH_uid'];
nAktuell := AuftragVersion(cUid);
nIfMatch := iVal(oParams.Values['if-match']);

if (nIfMatch <> nAktuell) then begin
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell));
oRes.AddPair('_OBS_HTTP_STATUS', 409);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'VERSION_CONFLICT'));
result := oRes.ToJSON();
exit;
end;

AuftragSpeichern(cUid, oBody); // setzt Version auf nAktuell + 1
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell + 1));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}/material'' - idempotentes Anlegen==

''POST'' erfasst eine Materialposition: Validierungsfehler -> 422, erfolgreiches Anlegen -> 201.

Gegen doppelte Sendungen schickt der Client den Header ''Idempotency-Key''. '''Das
Skript muss dafür nichts tun''' - der Server erkennt den Header, merkt sich das
Ergebnis und liefert bei einer Wiederholung mit demselben Schlüssel die
gespeicherte Antwort zurück, ohne das Skript erneut zu starten (siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz). Das Skript kümmert sich nur um seine Fachlogik:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
oVal: TJSONValue;
cUid, cArtikel, cNeueUid: string;
nMenge: integer;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];

// 1) Validierung -> 422 mit traceId.
// Wichtig: fachliche Ablehnung als 4xx melden, nicht als 200 mit
// Fehlertext - nur dann gibt der Server den Idempotency-Key wieder
// frei und der Client darf ihn nach Korrektur erneut verwenden.
cArtikel := '';
nMenge := 0;
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('artikel'); if (Assigned(oVal)) then cArtikel := oVal.Value;
oVal := oBody.GetValue('menge'); if (Assigned(oVal)) then nMenge := iVal(oVal.Value);
end;
if ((Empty(cArtikel)) or (nMenge <= 0)) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'artikel und menge sind Pflicht');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 2) Buchen. Die Transaktionssteuerung bleibt beim Skript; der
// Idempotenz-Speicher des Servers läuft getrennt davon und
// umschliesst diesen Block nicht.
cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);

// 3) Antwort vollständig aufbauen - genau sie wird eingefroren und bei
// einer Wiederholung erneut ausgeliefert.
oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('uid', cNeueUid);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''auth/logout'' - Abmelden==

Beim Abmelden soll das Gerät seine Sitzung wirklich verlieren - nicht erst mit dem
Ablauf des Tokens. Dafür genügt ein Antwortfeld; die Sperre führt der Server in
''RESTSRV_TOKEN'':

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
oVal: TJSONValue;
cAlle: string;
begin
oRes := TJSONObject.Create();
try
// Optional: {"alleGeraete": true} meldet den Techniker ueberall ab
cAlle := 'session';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('alleGeraete');
if (Assigned(oVal)) and (Lower(oVal.Value) = 'true') then begin
cAlle := 'all';
end;
end;

oRes.AddPair('_OBS_JWT_REVOKE' , cAlle);
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

Gesperrt wird die ganze Sitzung, also auch die Access-Token vorheriger
Erneuerungen. Ein zweiter Aufruf ist unschädlich. Kann der Server die Sitzung
nicht sperren, antwortet er mit '''503''' statt mit dem 204 des Skripts - die App
darf den Abmeldevorgang dann wiederholen.

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"tech1\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/auth/

{"token":"eyJ...","accessToken":"eyJ...","refreshToken":"eyJ...",
"expiresIn":3600,"serverTime":"2026-06-29T15:30:12+02:00"}

Bei falschen Zugangsdaten antwortet der Server mit '''401''' und dem Text aus dem
Authenticate-Skript als ''error.message''.

Auftrag lesen (liefert den ETag-Header):

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711
... ETag: 7

ändern mit korrektem If-Match -> 200, mit veraltetem If-Match -> 409:

curl -i -X PUT -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "If-Match: 7" -H "Content-Type: application/json" ^
-d "{\"status\":\"erledigt\"}" ^
https://api.meinserver.de/orders/4711

Material idempotent erfassen (zweiter Aufruf mit gleichem Key -> gleiche Antwort, keine Doppelbuchung):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Idempotency-Key: 9c84-7f2a-..." -H "Content-Type: application/json" ^
-d "{\"artikel\":\"A100\",\"menge\":3}" ^
https://api.meinserver.de/orders/4711/material

Die Antwort des zweiten Aufrufs trägt zusätzlich den Header
''Idempotent-Replay: true'' - daran ist erkennbar, dass sie aus dem Speicher kam
und nichts erneut gebucht wurde.

Token erneuern (Refresh-Token im Authorization-Header an denselben JWT-Endpunkt):

curl -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer <refreshToken>" ^
https://api.meinserver.de/auth/

Die Antwort enthält ein neues Paar. Das alte Refresh-Token ist damit verbraucht:
ein zweiter Aufruf mit demselben Token antwortet '''401'''. Erfolgt er innerhalb
von 60 Sekunden, bleibt die Sitzung bestehen (paralleler Refresh der App); später
gilt er als Wiedervorlage und die '''ganze Sitzung wird gesperrt''' - der
Techniker muss sich neu anmelden, und der Vorfall steht mit IP im Protokoll.

Abmelden (Access-Token im Authorization-Header):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/auth/logout

HTTP/1.1 204 No Content

Derselbe Token danach noch einmal verwendet:

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711

HTTP/1.1 401 Unauthorized

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00G9TOK09",
"message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden",
"traceId": "20260819T091233123-00001A"
}
}
</pre>

==Was zeigt das Beispiel?==

* Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422.
* Optimistic Concurrency über ''ETag'' (GET) und ''If-Match'' (PUT) -> 409 VERSION_CONFLICT.
* Idempotente Schreibzugriffe über den ''Idempotency-Key'' - '''vom Server erledigt''', das Skript enthält dafür keine Zeile Code.
* Rollenprüfung aus dem Token-Claim ''_OBS_JWT_CLAIM_roles'', nicht aus dem Body.
* JWT mit Custom-Claims (''tenant''/''roles'') und Refresh-Token mit Rotation - '''vom Server erledigt''', das Skript führt keine Sperrtabelle.
* Abmelden über ''_OBS_JWT_REVOKE'', wahlweise für diese Sitzung oder alle Geräte des Technikers.
* ''traceId'' im Fehler-Body für die Support-Nachverfolgung (auch als Header ''X-Trace-Id'').

OBS/Kostenpflichtige Module/RESTServer/Beispiel5

2026-08-19T10:15:50Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz=

Dieses Beispiel zeigt einen schreibenden Endpunkt für eine mobile App: Aufträge werden mit echten HTTP-Statuscodes aktualisiert, konkurrierende Änderungen über ETag/If-Match abgesichert (Optimistic Concurrency) und doppelte Sendungen über einen Idempotency-Key abgefangen. Die Anmeldung nutzt JWT mit Custom-Claims (Mandant, Rollen) und einem Refresh-Token.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App''
** API-Key: zufällig generiert
** JWT aktiv, JWT-Endpunkt ''auth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
* '''Endpunkte''' (alle dem Profil ''Public-API'' zugeordnet):
** ''orders/{uid}'' - Auftrag lesen/Ändern
** ''orders/{uid}/material'' - Material erfassen
** ''auth/logout'' - Abmelden
* '''Berechtigung:''' Zugang ''Mobile-App'' für alle drei Endpunkte freigeschaltet

==JWT-Authentifizierungs-Skript (Zugang)==

Stellt Mandant und Rollen als Custom-Claims aus und löst über ''_OBS_JWT_REFRESH_ID'' ein Refresh-Token aus. Bei einem Refresh ruft der Server im selben Skript die Methode ''Refresh'' auf. Die Hilfsfunktionen (''PasswortPasst'', ''TechnikerMandant'', ''TechnikerRollen'') sind illustrativ und projektabhängig.

{{Hinweis|Eine '''eigene Sperrtabelle für Refresh-jti ist nicht nötig'''.
Einmalgebrauch, Rotation und Widerruf führt der Server in ''RESTSRV_TOKEN'' -
das Skript entscheidet nur, '''ob''' und '''mit welchen Rechten''' die Sitzung
fortgesetzt wird. Frühere Fassungen dieses Beispiels zeigten eine Skript-Tabelle;
wer sie übernommen hat, kann sie entfernen.}}

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser, cPass: string;
begin
oRes := TJSONObject.Create();
try
cUser := ''; cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username'); if (Assigned(oVal)) then cUser := oVal.Value;
oVal := oBody.GetValue('password'); if (Assigned(oVal)) then cPass := oVal.Value;
end;

if (PasswortPasst(cUser, cPass)) then begin

oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser)); // z.B. "tech,lead"
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das Refresh-Token aus
// _OBS_JWT_REFRESH_EXP weggelassen -> Default 90 Tage
end else begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Login fehlgeschlagen');
end;
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------

function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
cUser: string;
begin
oRes := TJSONObject.Create();
try

cUser := oParams.Values['_OBS_JWT_SUBJECT'];

// Das vorgelegte Refresh-Token hat der Server bereits geprueft und
// entwertet. Hier wird nur entschieden, ob die Sitzung fortgesetzt
// werden darf - und mit welchen Rechten.
if (not TechnikerAktiv(cUser)) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
result := oRes.ToJSON();
exit;
end;

// Mandant und Rollen NEU lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.

oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , cUser);
oRes.AddPair('_OBS_JWT_SUBJECT' , cUser);
oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oRes.AddPair('_OBS_JWT_REFRESH_ID' , GlobalUID());
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}'' - ändern mit ETag / If-Match==

''GET'' liefert den Auftrag samt ''ETag'' (Version), ''PUT'' prüft Rolle und ''If-Match''.

<syntaxhighlight lang="pascal" line>
function Get(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
cUid: string;
nVer: integer;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];
if (not AuftragLesen(oParams.Values['_OBS_JWT_CLAIM_tenant'], cUid, oRes, nVer)) then begin
oRes.AddPair('_OBS_HTTP_STATUS', 404);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'NOT_FOUND'));
result := oRes.ToJSON();
exit;
end;
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nVer));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

//------------------------------------------------------------------------------

function Put(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
cUid: string;
nAktuell, nIfMatch: integer;
begin
oRes := TJSONObject.Create();
try
// nur Rolle "lead" darf ändern - Rolle kommt aus dem Token, nicht aus dem Body.
// Mit Trennzeichen suchen: ein blosses Pos('lead', ...) wuerde auch in
// "leadless" oder "teamlead" treffen.
if (Pos(',lead,', ',' + oParams.Values['_OBS_JWT_CLAIM_roles'] + ',') = 0) then begin
oRes.AddPair('_OBS_HTTP_STATUS', 403);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'FORBIDDEN_ROLE'));
result := oRes.ToJSON();
exit;
end;

cUid := oParams.Values['_OBS_PATH_uid'];
nAktuell := AuftragVersion(cUid);
nIfMatch := iVal(oParams.Values['if-match']);

if (nIfMatch <> nAktuell) then begin
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell));
oRes.AddPair('_OBS_HTTP_STATUS', 409);
oRes.AddPair('_OBS_HEADERS', oHdr);
oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'VERSION_CONFLICT'));
result := oRes.ToJSON();
exit;
end;

AuftragSpeichern(cUid, oBody); // setzt Version auf nAktuell + 1
oHdr := TJSONObject.Create();
oHdr.AddPair('ETag', xStr(nAktuell + 1));
oRes.AddPair('_OBS_HEADERS', oHdr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}/material'' - idempotentes Anlegen==

''POST'' erfasst eine Materialposition: Validierungsfehler -> 422, erfolgreiches Anlegen -> 201.

Gegen doppelte Sendungen schickt der Client den Header ''Idempotency-Key''. '''Das
Skript muss dafür nichts tun''' - der Server erkennt den Header, merkt sich das
Ergebnis und liefert bei einer Wiederholung mit demselben Schlüssel die
gespeicherte Antwort zurück, ohne das Skript erneut zu starten (siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz). Das Skript kümmert sich nur um seine Fachlogik:

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
oVal: TJSONValue;
cUid, cArtikel, cNeueUid: string;
nMenge: integer;
begin
oRes := TJSONObject.Create();
try
cUid := oParams.Values['_OBS_PATH_uid'];

// 1) Validierung -> 422 mit traceId.
// Wichtig: fachliche Ablehnung als 4xx melden, nicht als 200 mit
// Fehlertext - nur dann gibt der Server den Idempotency-Key wieder
// frei und der Client darf ihn nach Korrektur erneut verwenden.
cArtikel := '';
nMenge := 0;
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('artikel'); if (Assigned(oVal)) then cArtikel := oVal.Value;
oVal := oBody.GetValue('menge'); if (Assigned(oVal)) then nMenge := iVal(oVal.Value);
end;
if ((Empty(cArtikel)) or (nMenge <= 0)) then begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , 'VALIDATION_FAILED');
oErr.AddPair('message', 'artikel und menge sind Pflicht');
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
oRes.AddPair('_OBS_HTTP_STATUS', 422);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
exit;
end;

// 2) Buchen. Die Transaktionssteuerung bleibt beim Skript; der
// Idempotenz-Speicher des Servers läuft getrennt davon und
// umschliesst diesen Block nicht.
cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);

// 3) Antwort vollständig aufbauen - genau sie wird eingefroren und bei
// einer Wiederholung erneut ausgeliefert.
oRes.AddPair('_OBS_HTTP_STATUS', 201);
oRes.AddPair('uid', cNeueUid);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

==Endpunkt ''auth/logout'' - Abmelden==

Beim Abmelden soll das Gerät seine Sitzung wirklich verlieren - nicht erst mit dem
Ablauf des Tokens. Dafür genügt ein Antwortfeld; die Sperre führt der Server in
''RESTSRV_TOKEN'':

<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
oVal: TJSONValue;
cAlle: string;
begin
oRes := TJSONObject.Create();
try
// Optional: {"alleGeraete": true} meldet den Techniker ueberall ab
cAlle := 'session';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('alleGeraete');
if (Assigned(oVal)) and (Lower(oVal.Value) = 'true') then begin
cAlle := 'all';
end;
end;

oRes.AddPair('_OBS_JWT_REVOKE' , cAlle);
oRes.AddPair('_OBS_HTTP_STATUS', 204);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

Gesperrt wird die ganze Sitzung, also auch die Access-Token vorheriger
Erneuerungen. Ein zweiter Aufruf ist unschädlich. Kann der Server die Sitzung
nicht sperren, antwortet er mit '''503''' statt mit dem 204 des Skripts - die App
darf den Abmeldevorgang dann wiederholen.

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"tech1\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/auth/

{"token":"eyJ...","accessToken":"eyJ...","refreshToken":"eyJ...",
"expiresIn":3600,"serverTime":"2026-06-29T15:30:12+02:00"}

Bei falschen Zugangsdaten antwortet der Server mit '''401''' und dem Text aus dem
Authenticate-Skript als ''error.message''.

Auftrag lesen (liefert den ETag-Header):

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711
... ETag: 7

ändern mit korrektem If-Match -> 200, mit veraltetem If-Match -> 409:

curl -i -X PUT -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "If-Match: 7" -H "Content-Type: application/json" ^
-d "{\"status\":\"erledigt\"}" ^
https://api.meinserver.de/orders/4711

Material idempotent erfassen (zweiter Aufruf mit gleichem Key -> gleiche Antwort, keine Doppelbuchung):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Idempotency-Key: 9c84-7f2a-..." -H "Content-Type: application/json" ^
-d "{\"artikel\":\"A100\",\"menge\":3}" ^
https://api.meinserver.de/orders/4711/material

Die Antwort des zweiten Aufrufs trägt zusätzlich den Header
''Idempotent-Replay: true'' - daran ist erkennbar, dass sie aus dem Speicher kam
und nichts erneut gebucht wurde.

Token erneuern (Refresh-Token im Authorization-Header an denselben JWT-Endpunkt):

curl -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer <refreshToken>" ^
https://api.meinserver.de/auth/

Die Antwort enthält ein neues Paar. Das alte Refresh-Token ist damit verbraucht:
ein zweiter Aufruf mit demselben Token antwortet '''401'''. Erfolgt er innerhalb
von 60 Sekunden, bleibt die Sitzung bestehen (paralleler Refresh der App); später
gilt er als Wiedervorlage und die '''ganze Sitzung wird gesperrt''' - der
Techniker muss sich neu anmelden, und der Vorfall steht mit IP im Protokoll.

Abmelden (Access-Token im Authorization-Header):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/auth/logout

HTTP/1.1 204 No Content

Derselbe Token danach noch einmal verwendet:

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711

HTTP/1.1 401 Unauthorized

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00G9TOK09",
"message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden",
"traceId": "20260819T091233123-00001A"
}
}
</pre>

==Was zeigt das Beispiel?==

* Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422.
* Optimistic Concurrency über ''ETag'' (GET) und ''If-Match'' (PUT) -> 409 VERSION_CONFLICT.
* Idempotente Schreibzugriffe über den ''Idempotency-Key'' - '''vom Server erledigt''', das Skript enthält dafür keine Zeile Code.
* Rollenprüfung aus dem Token-Claim ''_OBS_JWT_CLAIM_roles'', nicht aus dem Body.
* JWT mit Custom-Claims (''tenant''/''roles'') und Refresh-Token mit Rotation - '''vom Server erledigt''', das Skript führt keine Sperrtabelle.
* Abmelden über ''_OBS_JWT_REVOKE'', wahlweise für diese Sitzung oder alle Geräte des Technikers.
* ''traceId'' im Fehler-Body für die Support-Nachverfolgung (auch als Header ''X-Trace-Id'').

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-08-19T10:15:30Z

Rademacker:

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

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

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# 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 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.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|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 [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Die früheren Felder '''Sub-URL''' und '''Version''' werden nicht mehr ausgewertet. Eine Versionskennung wird ggf. als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''). Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|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/[Pfad-Template]

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.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen bleiben absichtlich stehen und werden ab 24 Stunden im Protokoll gemeldet - sie sind ein Support-Fall, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==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''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* 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.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde unterbrochen. Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen, dann den Eintrag in '''RESTSRV_IDEMPOTENCY''' entfernen.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Endpunkte

2026-08-19T10:15:05Z

Rademacker:

{{Kostenpflichtige Module}}

= Endpunkte =

Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
realisiert und ist genau einem Server-Profil zugeordnet.

== Routing über Pfad-Templates ==

Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
'''Platzhalter''' enthalten:

* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
* '''Platzhalter''' in geschweiften Klammern – z. B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.

Beispiele für gültige Templates:

{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}

=== Präzedenz bei mehreren Treffern ===

Passen mehrere Templates auf denselben Pfad, '''gewinnt das spezifischste''' –
also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code>
das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf
<code>/orders/{uid}</code> matcht.

== Hauptfelder eines Endpunkts ==

{| class="wikitable"
! Feld !! Spalte !! Zweck
|-
| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code>
|-
| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
|-
| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
|-
| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
|-
| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
|-
| '''Info''' || – || Dokumentations-Freitext
|-
| '''Datei-Upload''' || <code>re_upload</code> || Erlaubt Datei-Uploads an diesem Endpunkt (<code>0</code> = aus, <code>1</code> = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
|-
| '''Max. Upload-Grösse''' || <code>re_upload_size</code> || Maximale Dateigrösse in MB. Leer/0 = Standard 25 MB. Überschreitung wird mit 413 abgelehnt.
|}

== Pfad-Parameter im Skript ==

Die aus den Platzhaltern erfassten Werte stehen im Endpunkt-Skript als
reservierte Parameter mit Präfix <code>_OBS_PATH_</code> zur Verfügung:

<syntaxhighlight lang="pascal">
function Get(oParams: TStrings; oBody: TJSONObject): string;
var cUid: string;
begin
cUid := oParams.Values['_OBS_PATH_uid']; // aus /orders/{uid}
// ...
end;
</syntaxhighlight>

Da der Präfix <code>_OBS_</code> für von außen gelieferte Header/Query-Parameter
gesperrt ist, können diese Werte nicht durch den Client überschrieben werden.

== Datei-Uploads ==

Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.

Die maximal zulässige Dateigrösse wird pro Endpunkt über <code>re_upload_size</code>
(in MB) festgelegt; ohne Angabe gilt der Standard von '''25 MB'''. Wird das
Limit überschritten, antwortet der Server mit '''413 Payload Too Large'''. Für
Uploads gilt nicht das JSON-Body-Limit (10 MB), sondern dieses Endpunkt-Limit.
Der Originalname (beim resumable Upload über den Header <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit 413/400 abgelehnt. Dem Skript stehen Pfad, Name und Content-Type als <code>_OBS_UPLOAD_*</code>-Parameter zur Verfügung (Details: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

Unterstützt werden zwei Übertragungsarten:

* '''Einfacher Upload''' per <code>multipart/form-data</code> (eine Datei pro Request).
* '''Resumable/Chunked Upload''' per <code>Content-Range</code> (grosse Dateien, fortsetzbar nach Abbruch).

Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und
übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage,
DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und
Beispiele: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== HTTP-Methode ==

Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
Pfad-Formen (z. B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
'''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.

== URL-Struktur ==

<pre>
http://[Host][:Port][Pfad-Template]
</pre>

Beispiele:
* <code>https://api.meinserver.de/orders</code>
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>

== Versionierung ==

Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z. B. <code>/orders/v1</code> oder
<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:

# Bestehenden Endpunkt unverändert lassen.
# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
# Berechtigungen für neue Konsumenten setzen.
# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.

== Zugriffskontrolle ==

Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
dürfen. Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
Zugriff '''pro Pfad-Form''' granular vergeben (z. B. Lesen von
<code>/orders/{uid}</code> erlauben, aber das ändernde
<code>PUT /orders/{uid}/modules/{code}</code> nicht).

== Caching ==

Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
(TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher
erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
zwingend sofort.

== HTTP-Fehlercodes ==

{| class="wikitable"
! Code !! Ursache
|-
| '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
|-
| '''403''' || Zugang fehlt in der Berechtigungsliste
|-
| '''401''' || API-Key ungültig/fehlend, JWT abgelaufen oder Sitzung gesperrt (''AUTH_EXPIRED'')
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>)
|-
| '''429''' || Rate-Limit überschritten; die Antwort enthält den Header <code>Retry-After</code>
|-
| '''503''' || Eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet; die Antwort enthält <code>Retry-After</code>
|-
| '''409''' || Ein früherer Aufruf mit demselben <code>Idempotency-Key</code> ist ohne Ergebnis geblieben (<code>IDEMPOTENCY_UNRESOLVED</code>)
|-
| '''422''' || Derselbe <code>Idempotency-Key</code> wurde mit '''anderem''' Inhalt gesendet (<code>IDEMPOTENCY_KEY_REUSED</code>)
|-
| '''400''' || Die Anfrage wurde unverschlüsselt an einen TLS-Port geschickt (<code>http</code> statt <code>https</code>). Die Abweisung erfolgt vor Authentifizierung und Endpunkt-Skript
|}

Jede Fehlerantwort besteht aus einem <code>error</code>-Objekt mit
maschinenlesbarem Code - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. <code>201</code>, <code>204</code>, <code>409</code>, <code>422</code>) sowie Response-Header wie <code>ETag</code> oder <code>Location</code> - siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Idempotenz ==

Schickt ein Konsument bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code>
oder <code>DELETE</code> den Header <code>Idempotency-Key</code>, sorgt der Server
selbst dafür, dass eine wiederholte Sendung '''keine Zweitwirkung''' hat. Das gilt
für '''jeden''' Endpunkt - es muss weder am Endpunkt etwas eingestellt noch im
Skript etwas programmiert werden.

{| class="wikitable"
! Situation !! Antwort des Servers
|-
| Erster Aufruf || Endpunkt läuft normal, das Ergebnis wird zum Schlüssel gespeichert
|-
| Wiederholung, gleicher Inhalt || '''Gespeicherte Antwort''' (gleicher Statuscode, gleicher Body, gleiche Header) plus Header <code>Idempotent-Replay: true</code>. Das Skript läuft '''nicht'''
|-
| Wiederholung, anderer Inhalt || '''422''' <code>IDEMPOTENCY_KEY_REUSED</code> - derselbe Schlüssel für einen anderen Inhalt ist ein Client-Fehler
|-
| Erster Aufruf läuft noch || '''503''' <code>IDEMPOTENCY_IN_PROGRESS</code> mit <code>Retry-After</code>. Beim nächsten Versuch liegt die gespeicherte Antwort vor
|-
| Früherer Aufruf ohne Ergebnis || '''409''' <code>IDEMPOTENCY_UNRESOLVED</code>. Der Dienst wurde zwischen Verarbeitung und Festschreiben unterbrochen; ob die Buchung stattgefunden hat, ist unbekannt und von Hand zu klären
|}

Wichtig für die Auslegung eines Endpunkts:

* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* Antwortet das Skript mit '''4xx''' (fachliche Ablehnung), wird der Schlüssel wieder '''freigegeben''' - der Konsument darf ihn nach Korrektur erneut verwenden. Sonst würde ein einziger Validierungsfehler den Schlüssel dauerhaft blockieren.
* Endet die Verarbeitung mit '''5xx''' oder einem Skript-Fehler, bleibt der Schlüssel belegt und der Fall wird protokolliert. Das ist Absicht: lieber ein Fall für den Support als eine mögliche Doppelbuchung.

Der Schlüssel gilt je '''Zugang, Methode und Pfad'''. Derselbe
<code>Idempotency-Key</code> an einem anderen Endpunkt ist damit ein eigener
Vorgang - der Konsument muss ihn nicht global eindeutig vergeben, aber pro Vorgang
'''stabil wiederverwenden''' (also nicht bei jedem Wiederholversuch neu erzeugen).

Die Einträge stehen in <code>RESTSRV_IDEMPOTENCY</code> und werden nach 30 Tagen
automatisch aufgeräumt. Einträge ohne Ergebnis werden '''nicht''' automatisch
gelöscht, sondern im Protokoll gemeldet.

== WebHooks ==

WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
gespeichert und der Endpunkt anschließend automatisch gelöscht.

Typischer Einsatz: OBS stösst einen Vorgang bei einem Fremdsystem an (Bezahldienst,
Versanddienstleister) und gibt diesem eine Rückruf-Adresse mit, die nur '''ein
einziges Mal''' gültig ist. Damit kann die Adresse nicht später erneut - oder von
jemand anderem - benutzt werden.

Ablauf:

# OBS legt einen Eintrag in <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, dessen Feld '''WebHook''' (<code>re_webhook</code>) auf diesen Eintrag zeigt. Ein Skript wird für diesen Endpunkt nicht gepflegt.
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
# Das Fremdsystem ruft die Adresse auf. Der Server legt den übergebenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code> ab, antwortet mit <code>{"status": "ok"}</code> und '''löscht den Endpunkt'''.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.

{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
normalen Endpunkt mit Skript anlegen.}}

OBS/Kostenpflichtige Module/RESTServer/Beispiel1

2026-08-19T10:14:47Z

Rademacker:

{{Kostenpflichtige Module}}

=Beispiel 1: Daten-Abruf mit JWT-Authentifizierung=

In diesem Beispiel werden Steuerungs-Variablen aus OBS abgerufen und auf einer Webseite ausgegeben. Der Zugang ist mit JWT-Pflicht eingerichtet, der Konsument muss sich daher zuerst anmelden und einen Token bezogen haben.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' mit Bindung 0.0.0.0:443
* '''Zugang:''' ''Web-Dashboard''
** API-Key: zufaellig generiert
** JWT aktiv, JWT-Endpunkt ''oauth'', JWT-Key zufaellig, JWT-Exp 60 (Minuten)
** CORS-Origins: ''https://dashboard.kunde.de''
* '''Endpunkt:''' ''steuerung/v1'', dem Profil ''Public-API'' zugeordnet
* '''Berechtigung:''' Zugang ''Web-Dashboard'' fuer Endpunkt ''steuerung/v1'' freigeschaltet

==JWT-Authentifizierungs-Skript (Zugang)==

Wird ueber die Zugaenge-Liste mit '''F7''' geoeffnet. Pruefen, ob Benutzername/Passwort gegen die OBS-Benutzerverwaltung passen.

<syntaxhighlight lang="pascal" line>
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
oVal : TJSONValue;
cUser : string;
cPass : string;
cSql : string;
qUser : TxFQuery;
lOk : Boolean;
begin
oRes := TJSONObject.Create();
try
cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
oVal := oBody.GetValue('username');
if (Assigned(oVal)) then begin
cUser := oVal.Value;
end;
oVal := oBody.GetValue('password');
if (Assigned(oVal)) then begin
cPass := oVal.Value;
end;
end;

cSql := 'SELECT u_nr, u_name FROM benutzer' +
' WHERE u_login = ' + DB_SQLVal(cUser) +
' AND u_passwort_hash = ' + DB_SQLVal(HashPasswort(cPass)) +
' AND u_aktiv = ' + DB_SQLVal('1');

// DB_SOpen liefert true, wenn die ABFRAGE lief - nicht, wenn ein
// Datensatz gefunden wurde. Ohne die EoF-Pruefung wuerde jede
// Anmeldung gelingen, sobald das SQL fehlerfrei ist.
lOk := false;
if (DB_SOpen(oDB, cSql, qUser)) then begin
if (not qUser.EoF) then begin
lOk := true;
oRes.AddPair('status' , 1);
oRes.AddPair('_OBS_JWT_ID' , qUser.A2C('u_nr'));
oRes.AddPair('_OBS_JWT_SUBJECT' , qUser.A2C('u_name'));
oRes.AddPair('_OBS_JWT_AUDIENCE', 'dashboard');
end;

end;
DB_Close(qUser);

if (not lOk) then begin
oRes.AddPair('status', 9);
oRes.AddPair('error' , 'Benutzer oder Passwort ist falsch');
end;

result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;
</syntaxhighlight>

{{Hinweis|Hier steht in ''_OBS_JWT_ID'' die Benutzernummer - derselbe Wert also bei
jeder Anmeldung desselben Benutzers. Das ist zulässig: der Server führt seine
Sitzungen über eigene Kennungen (''sid''/''rid''), nicht über das ''jti'' des
Skripts. Mehrfache und parallele Anmeldungen eines Benutzers sind damit
unproblematisch.}}

==Endpunkt-Skript ''steuerung/v1''==

Liefert eine Liste von Steuerungs-Werten zurueck. Die Auswertung der JWT-Claims sorgt dafuer, dass nur Audience ''dashboard'' Daten erhaelt.

<syntaxhighlight lang="pascal" line>
procedure _AddVar(oArr: TJSONArray; const cVar: string);
var oWert : TJSONObject;
cTitel : string;
cData : string;
cEinh : string;
lString: Boolean;
lAlign : Boolean;
begin
if (ST_Variable(oDB, cVar, cTitel, cData, cEinh, lString, lAlign)) then begin
oWert := TJSONObject.Create();
oWert.AddPair('variable', cVar);
oWert.AddPair('titel' , cTitel);
oWert.AddPair('wert' , cData);
oWert.AddPair('einheit' , cEinh);
oArr.Add(oWert);
end;
end;

//------------------------------------------------------------------------------

//------------------------------------------------------------------------------
// Hilfsfunktion: Fehlerantwort im einheitlichen Format aufbauen.
// Fachliche Ablehnungen als 4xx melden, nicht als 200 mit Fehlertext.
//------------------------------------------------------------------------------

function _Fehler(oParams: TStrings; nStatus: integer; const cCode, cMsg: string): string;
var oRes: TJSONObject;
oErr: TJSONObject;
begin
oErr := TJSONObject.Create();
oErr.AddPair('code' , cCode);
oErr.AddPair('message', cMsg);
oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);

oRes := TJSONObject.Create();
try
oRes.AddPair('_OBS_HTTP_STATUS', nStatus);
oRes.AddPair('error', oErr);
result := oRes.ToJSON();
finally
MyFreeAndNil(oRes);
end;
end;

function Get(oParams: TStrings; oBody: TJSONObject): string;
var oArr: TJSONArray;
begin
// Audience-Pruefung: nur Dashboard-Tokens akzeptieren
if (oParams.Values['_OBS_JWT_AUDIENCE'] <> 'dashboard') then begin
result := _Fehler(oParams, 403, 'FORBIDDEN_ROLE', 'Token nicht für diese Anwendung ausgestellt');
exit;
end;

oArr := TJSONArray.Create();
try
_AddVar(oArr, 'WERT_1');
_AddVar(oArr, 'WERT_2');
_AddVar(oArr, 'WERT_3');
_AddVar(oArr, 'WERT_4');
result := oArr.ToJSON();
finally
MyFreeAndNil(oArr);
end;
end;
</syntaxhighlight>

==JavaScript-Client (Browser)==

Im Browser werden zwei Aufrufe gemacht: erst Token holen, dann Daten lesen.

<syntaxhighlight lang="javascript" line>
const API_BASE = 'https://api.meinserver.de';
const API_KEY = '[API-KEY]';

async function login(username, password) {
const res = await fetch(`${API_BASE}/oauth/`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'apikey': API_KEY },
body: JSON.stringify({ username, password })
});
if (!res.ok) throw new Error('Login fehlgeschlagen');
const data = await res.json();
return data.token;
}

async function ladeSteuerung(token) {
const res = await fetch(`${API_BASE}/steuerung/v1`, {
method: 'GET',
headers: {
'apikey': API_KEY,
'Authorization': 'Bearer ' + token
}
});
if (!res.ok) throw new Error('Abruf fehlgeschlagen: ' + res.status);
return res.json();
}

async function zeigeTabelle() {
const token = await login('mitarbeiter', 'geheim');
const werte = await ladeSteuerung(token);

const tbl = document.getElementById('steuerung');
werte.forEach(w => {
const tr = document.createElement('tr');
tr.innerHTML = `<td>${w.titel}</td><td>${w.wert} ${w.einheit}</td>`;
tbl.appendChild(tr);
});
}

zeigeTabelle();
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"mitarbeiter\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/oauth/

Antwort:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 3600,
"serverTime": "2026-08-19T09:12:33+02:00"}

Da das Skript kein ''_OBS_JWT_REFRESH_ID'' liefert, enthält die Antwort kein
''refreshToken'' - der Client meldet sich nach Ablauf der 60 Minuten neu an.

Daten abrufen:

curl -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJhbGciOi..." ^
https://api.meinserver.de/steuerung/v1

==Was zeigt das Beispiel?==

* Zweistufige Anmeldung: API-Key + JWT.
* Sichere Trennung von Konsumenten-Gruppen ueber die Audience-Claim.
* Eigenes Authentifizierungs-Skript pro Zugang.
* Browser-Zugriff ueber CORS-erlaubtes Origin.
* Anmeldung ohne Refresh-Token: einfachster Fall, der Token laeuft nach der Zeit aus ''JWT-Exp'' ab.