JSONServerAPI

Verarbeitungsablauf

1. jsaService.ctl übernimmt HTTP-Methode, Endpunkt, Header und Body.
2. OPTIONS, APITEST, KEEPALIVE und AUTHINFO werden als technische Serviceaufrufe behandelt.
3. Für Fachaufrufe werden API-Key und/oder Basic Authentication entsprechend der Konfiguration geprüft.
4. Endpunkt, Inhaltslänge und JSON-Struktur werden validiert.
5. frmJsaMain.frm ordnet den großgeschriebenen Endpunkt dem aktiven Handler zu.
6. Der Handler prüft fachliche Pflichtfelder, führt die Portalum-Funktion aus und erzeugt JSON.

Technische Aufrufe und Authentisierung

Diese technischen Aufrufe werden vor der Fachauthentisierung behandelt. Fachaufrufe können den Header X-API-Key und/oder den HTTP-Header Authorization: Basic … benötigen. Zugangsdaten und Schlüssel dürfen weder in URLs noch in allgemein zugänglichen Protokollen stehen.

Aktive Fachendpunkte

Gemeinsame Datenkonventionen

Sitzungen

SESSIONSTART

{
  "Device": { "ID": "POS-01", "Name": "Webkasse Eingang" },
  "Stock": 25000
}

SESSIONINFO

SESSIONEND

Datenbank, Reader, Passagen und Artikel

DBINFO

Die Antwort enthält DB.UUID, DB.Type, DB.Name, DB.Version, DLL Version und App Version. Damit kann ein Client Zielsystem und kompatible Versionen protokollieren.

READERLIST

Jeder Eintrag enthält OID, Name, Passage (Name, OID), Standort (name, OID), Ausgangs- und Zielzone (Zone.From.*, Zone.To.*), Typ (Type.ID, Type.Name) und Reader.

PASSAGENLIST

Jede Passage liefert OID, Caption, Number, Standort (Location.ID, Location.Name) sowie Ausgangs- und Zielzone (FromZone.*, ToZone.*).

ARTIKELLIST

Ticket- und Wertkarteninformationen

CARDINFO

Die Anfrage muss genau einen geeigneten Identifikator enthalten: OID, Barcode oder RFID. Transaction steuert optional die transaktionsbezogene Behandlung.

Wird keine Karte gefunden, enthält die Antwort ein entsprechendes Info-Feld.

VALUECARDINFO

Die Anfrage identifiziert die Wertkarte über OID oder CardCode. Die Antwort enthält OID, CardCode, Kunde (Customer.OID, Customer.Name), Title, Value.Min, Value.Max, Credit, AccountNumber, Discounts, IsRFID und Blocked. Bei unbekannter Karte wird Info: Not Found geliefert.

VALUECARDCHANGE

Der Handler prüft Mindest-/Höchstwerte, Sperren und den zulässigen Kredit, bevor er die Buchung ausführt.

Verkauf und Bestand

EXECUTESALE

{
  "SessionID": 4711,
  "Items": [
    { "OID": 1001, "Amount": 2, "Price": 1250 }
  ],
  "PaymentValue": 2500,
  "PaymentMethod": "CASH"
}

STOCKCHANGE

Die Anfrage enthält SessionID, Type und Amount in Cent. Die Antwort liefert Success, Session.ID, Session.Name, Type, Amount und Info.

Antwort- und Fehlerbehandlung

{
  "Code": 406,
  "Message": "Fachliche Prüfung fehlgeschlagen",
  "Number": 0,
  "Description": "Beschreibung der Ursache",
  "Source": "RequestExecuteSale"
}

{
  "error": {
    "code": 401,
    "message": "Authentisierung erforderlich"
  }
}

Clients müssen deshalb sowohl HTTP-Statuscodes als auch beide JSON-Fehlerformen auswerten. Ein HTTP-Erfolg allein bestätigt noch keine erfolgreiche Fachbuchung.

Technische Prüfung

1. Mit APITEST die Erreichbarkeit des Diensts prüfen.
2. Mit AUTHINFO die erwartete Authentisierung ermitteln.
3. Header, Endpunkt, Content-Type und Inhaltslänge protokollieren, sensible Werte dabei maskieren.
4. Eine Sitzung starten und die zurückgegebene Session.ID für nachfolgende Aufrufe verwenden.
5. Beträge als Centwerte senden und Base64-Belege vor der Nutzung dekodieren.
6. Sitzungen kontrolliert mit SESSIONEND abschließen.

Quellfundstellen