Publish/Subscribe Schnittstelle

Überblick

Mit der PubSub Schnittstelle können Echtzeitbenachrichtigungen über neue Belege und den Status von Belegen empfangen werden. Die Pub/Sub Schnittstelle nutzt WebSockets, um bidirektionale Kommunikation zwischen Server und Client zu ermöglichen.

Alle Nachrichten auf der Verbindung werden als JSON-Objekte serialisiert. Die Verbindung mit dem Server erfordert zunächst keine Authentifizierung, bevor jedoch auf der Verbindung Aktionen durchgeführt werden können, muss eine Authentifizierungsnachricht gesendet werden.

{
    "type": "authorize",
    "token": [token]
}

Das Access Token kann vom Token-Endpunkt des OAuth2 servers unter https://web.adminapp.de/connect/token bezogen werden. Kassengeräte nutzen dafür den Client Credentials Grant, andere Anwendungen können den Authorization Code Grant nutzen.

Benachrichtigungen abonnieren

Um Benachrichtigungen zu empfangen, müssen Clients Benachrichtigungsthemen abonnieren. Dazu sendet der Client eine subscribe-Aktion. Diese Nachricht folgt folgendem Schema:

{
    "type": "subscribe",
    "subscription": {
        "type": [subscription type],
        "cashpointUid": [...]
    }
}
Das innere subscription Objekt muss ein Attribut enthalten, das angibt, für welches Kassengerät Benachrichtigungen angefordert sind. Je nach Benachrichtigungstyp kann dieses Objekt auc weitere Attribute enthalten.

Neue Belege

Benachrichtigungen für neue Belege enthalten eine HTML-Repräsentation des Inhalts des Belegs und den Inhalt für einen QR-Code. Der QR-Code kann entweder von der AdminApp gescannt werden um den Beleg im eigenen Konto zu speichern oder ohne die AdminApp, um den Beleg anonym herunterzuladen.
Abonnement starten
{
    "type": "subscribe",
    "subscription": {
        "type": "receipts",
        "cashpointUid": [...]
    }
}
Benachrichtigungsinhalt
{
    "type": "new-receipt",
    "receiptId": "123456789",
    "receiptHtmlUrl": "https://example.org/123456789.html",
    "qrContent": "https://example.org/receipt/123456789"
}

Belegstatus

Diese Benachrichtigung wird ausgelöst wenn sich der Status eines Belegs ändert. Das geschieht wenn ein Beleg gedruckt, vom Kunden heruntergeladen, oder einer Admin-ID zugewiesen wurde.

Abonnement starten
{
    "type": "subscribe",
    "subscription": {
        "type": "receipt-updates",
        "cashpointUid": [...]
    }
}
Benachrichtigungsinhalt
{
    "type": "receipt-status",
    "receiptId": "123456789",
    "statusChange": ["printed"],
}
Gültige Werte in statusChange sind printed, assigned, downloaded, discarded.
  • printed: Der Beleg wurde auf Papier gedruckt.
  • assigned: Der Beleg wurde einem AdminApp-Benutzer zugeordnet und ist in dessen Account gespeichert.
  • downloaded: Der Beleg wurde anonym heruntergeladen.
  • discarded: Der Beleg wurde vom Kunden abgelehnt.