Rechnungsverarbeitung in asello App

Diese Variante ermöglicht der externen Software Rechnungsdaten an die asello Cloud zu senden, diese anschließen in der lokalen asello Windows App zu öffnen und abzuschließen. 

Vorteile

• Nutzung der bestehenden asello Software (Hardware Implementierung, Ausdruck, Bon-Drucker, Scanner, Kartenterminals, etc.)
• TSE-Implementierung (Deutschland)
• Weitere Positionen verrechenbar

Nachteile

• Komplexere Implementierung
• Benutzer muss 2 unterschiedliche Softwaresysteme bedienen

Ablauf

1. Im ersten Schritt wird von der externen Software ein neuer Beleg im asello Kassensystem "geparkt". Das heißt, dass der Beleg in der Datenbank gespeichert, aber noch nicht final abgeschlossen wird. Dieser Schritt erfolgt über die asello Rest-Schnittstelle.
2. Über einen weiteren Rest-Aufruf wird der Beleg automatisch in der asello Windows App geöffnet. Die asello Cloud kommuniziert dabei von der API mit der lokal installierten App über eine Websocket-Verbindung und führt dabei das Kommando zum Öffnen des Beleges aus.
3. Der Beleg öffnet sich in der App und muss vom Bediener weiter verarbeitet werden. Hier kann der Beleg durch "Abbruch" verworfen, oder final abgeschlossen werden.
4. Nach dem Abbruch oder dem Abschluss des Vorganges wird die externe Software per Webhook benachrichtigt. Im Webhook wird die Id und die Referenznummer, sowie die Aktion mitgegeben. Für dieses Konzept wird der Webhook "receipt.created" verwendet, der immer dann ausgelöst wird, wenn in asello ein Beleg erstellt wurde. Die mitgegebene Id und Referenznummer kann anschließend dazu verwendet werden, um das erstellte Dokument abzurufen. Alternativ zum Webhook kann die API für ein Polling der Zugriffe genutzt werden.

Eine zu häufige Abfrage der asello API (zu häufiges Polling) führt zu einem hohen Ressourcenverbrauch und kann automatisch blockiert werden.

Technische Implementierung

Rechnung parken

Zuerst wird die Rechnung geparkt.  Dafür müssen Daten über die Rechnung und deren Produkte mitgegeben werden. Wie ein Aufruf mit einem Produkt aussieht sehen Sie im folgenden Beispiel.

https://kassa.asello.at/api/v2/open

{
  "paymentType": "Cash",
  "cashRegisterId": 34950,
  "items": [
    {
      "name": "Blumentopf",
      "description": "Grosser Blumentopf für den Gartenbereich",
      "netPrice": 33.61,
      "grossPrice": 39.99,
      "productId": 597349,
      "vatRate": 20,
      "quantity": 1
    }
  ]
}

Nachdem Sie die Anfrage geschickt haben, antwortet der Server mit den Rechnungsdaten.

{
    "items": [
        {
            "id": 7420479,
            "name": "Blumentopf Blumentopf",
            "description": "Großer Blumentopf für den Gartenbereich Grosser Blumentopf für den Gartenbereich",
            "netPrice": 33.610000,
            "grossPrice": 40.330000,
            "productId": 597349,
            "vatRate": 20.00000,
            "quantity": 1.000000,
            "type": "Simple",
            "childItems": [],
            "state": "New"
        }
    ],
    "discount": 0.00000,
    "id": 1906664,
    "timeStamp": "2021-10-22T13:33:12.7377871+02:00",
    "type": "Receipt",
    "cashRegisterId": 34950,
    "userId": 745989,
    "sumCalculation": "Gross",
    "isDeleted": false
}

Device Id

• Woher weiß ich welches Device ich nehmen soll?
  • Name eingeben → Benutzer-Schulung oder einmal einrichten
  • Terminal-Server-Session: Session-Id wird gesetzt mit Computername + Session-Id

Damit anschließend die Rechnung in Ihrer asello Anwendung automatisch geöffnet werden kann, benötigen Sie die Device Id Ihres Gerätes. Diese können Sie über eine GET-Anfrage an die Rest-API erhalten.

https://kassa.asello.at/api/v2/online/connections

Die Anfrage liefert folgende Antwort:

{
    "@odata.context": "http://schema.asello.at/api/v2/$metadata",
    "@odata.count": 1,
    "totalCount": 1,
    "value": [
        {
            "connectionId": "CPwa4TubY-xBMeZRkaBcYw717304a61",
            "deviceId": "8c1ff1ed-f04b-414d-95ba-b641fcc0fb0f",
            "createdAt": "2021-10-22T10:24:48.8320516+00:00",
            "lastLivetick": "2021-10-22T10:52:32.5914169+00:00",
            "deviceName": "Lokal asello",
            "deviceModel": "Chrome 94.0",
            "deviceNumber": 3,
            "devicePlatform": "Browser Chrome",
            "deviceVersion": "1.16.14",
            "version": "1.16.14",
            "platform": "Browser Chrome",
            "clientName": "",
            "sessionId": ""
        }
    ]
}

Hier können Sie nun "deviceId" unter dem Attribut "value" finden.

Rechnung öffnen

Nun müssen Sie die Rechnung nur noch in Ihrer asello Anwendung öffnen. Dies geschieht ebenfalls durch einen POST-Befehl an die asello Rest-API.

https://kassa.asello.at/api/v2/online/commands

Geben Sie im Body des POST-Befehls folgende Attribute mit:

Geben Sie unter "args" die Id mit, die Sie beim Parken der Rechnung als Antwort vom Server erhalten haben. Diese wird benötigt, um die richtige Rechnung in der Anwendung zu öffnen.

{
  "deviceId": "8c1ff1ed-f04b-414d-95ba-b641fcc0fb0f",
  "key": "open-parked",
  "args": "1906505"
}

Anschließend sehen Sie, dass sich die geparkte Rechnung in Ihrer asello Anwendung geöffnet hat. Dort können Sie die Rechnung nun weiter verarbeiten. Die Anfrage liefert außerdem folgende Antwort:

{
    "id": "9b555cd3-ef84-43fd-a49f-6a38eb809e39",
    "deviceId": "8c1ff1ed-f04b-414d-95ba-b641fcc0fb0f",
    "key": "open-parked",
    "args": "1906505",
    "connectionIds": "QTraia6lHUEHffG5jV6feA717304a61",
    "state": "Pending",
    "createdAt": "2021-10-22T13:33:15.6467041+02:00"
}

Kasse wechseln

Die Rest-Schnittstelle bietet ebenfalls die Möglichkeit die Kasse vor öffnen der Rechnung zu wechseln.

https://kassa.asello.at/api/v2/online/commands

Geben Sie im Body des POST-Befehls folgende Attribute mit:

{
  "deviceId": "8c1ff1ed-f04b-414d-95ba-b641fcc0fb0f",
  "key": "change-cash-register",
  "args": "34950"
}

Die Befehl liefert folgende Antwort:

{
    "id": "7c7f0934-602a-40e3-b349-587a5f790ba0",
    "deviceId": "8c1ff1ed-f04b-414d-95ba-b641fcc0fb0f",
    "key": "change-cash-register",
    "args": "34950",
    "connectionIds": "1-8DCRBeLULg2Om5J_YAJAa40b2b5e1",
    "state": "Pending",
    "createdAt": "2021-10-22T15:11:11.76544+02:00"
}