Bessa Connector API

v30 14.12.2023 - API Version 1.2.11

1 Heartbeat
2 Tables
3 Article
4 Menus
5 New Order
6 Cancel Order
7 Mark Order. Done
8 Open items on table
9 Pay items on table
10 Update the POS about new orders (deprecated - 1.2.4)
11 Update the POS about new orders (new - 1.2.4)
12 Create bookings

Die Daten für den Connecter werden vom Kassensystem über einen REST-Server zur Verfügung gestellt. Im folgenden Dokument werden die API Calls mit diesem Server beschrieben. Als Beispiel wird hier angenommen dass der Webserver unter `192.168.1.1:8080/treuepass/` erreichbar ist.

Heartbeat

Alle 30 Sekunden wird der Status des Kassensystems abgefragt und an die Bessa Server weitergeleitet. Damit wird sichergestellt, dass das Kassensystem erreichbar ist und Bestellungen übetragen werden können.

Request

## Heartbeat
curl "http://192.168.1.1:8080/treuepass/heartbeat"

Response

{
  "active": true,
  "canOrder": true,
  "resync": false,
  "version": "1.2.4"
}

Response Structure

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
active	boolean	false
canOrder	boolean	false
resync	boolean	false
version	string	false	Semantic Version of the API

Tables

Damit man Bestellungen auf dem richtigen Tisch verbuchen kann, muss eine Liste der Tischgruppen inklusive Tische an den Bessa Server übetragen werden.

Request

## Tables

curl "http://192.168.1.1:8080/treuepass/tables/"

Response

[
  {
	"id": "31e04cb2-cb69-4d97-8ec0-6dcaac2b1e85",
    "name": "5",
  	"isActive": true   	
  },
  {
	"id": "4125123-cb69-4d97-8ec0-6dcaac2b1e85",
    "name": "6",
  	"isActive": true   	
  }
]

Response Structure

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
id	string	false	Unique ID of the table on the POS
name	string	false	Name of the table (to be displayed to the user)
isActive	boolean	false	If the table is active on the POS and orders can be placed on it

Article

Damit der User bestellen kann müssen Artikelgruppe, Artikel und Beilagen an den Bessa Server übertragen werden.

Request

## Article
curl "http://192.168.1.1:8080/treuepass/articles/"

Repsonse

[
  {
    "id": "5eae070f-f62f-4e49-aab8-3588d79ac2eb",
    "name": "Pizza",
    "sort": 0,
    "fromHour": "12:00",
    "toHour": "14:00",
    "articles": [
      {
        "id": "31e04cb2-cb69-4d97-8ec0-6dcaac2b1e85",
        "name": "Pizza Salami",
        "description": "mit Salami, Käse",
        "allergens": "A,B,C",
        "grossPrice": 899,
        "prices": [899, 999, 1099]
        "tax": 650,
        "isActive": true,
        "type": 4,
        "sort": 0,
        "modifiers": [
        ]
      },
      {

        "id": "e400bb4a-25c3-4d1d-bfa2-774034a84a17",
        "name": "Wunschpizza",
        "description": "Bau dir deine eigene Wunschpizza",
        "allergens": "A,B,C",
        "grossPrice": 899,
        "tax": 1000,
        "isActive": true,
        "type": 4,
        "sort": 1,
        "modifiers": [
          {
            "id": "159434e3-cb49-4301-b929-855e52fe7ae3",
            "name": "Fleisch",
            "min": 0,
            "max": 3,
            "ignorePrice": true,
            "sort": 0,
            "articles": [
              {
                "id": "e400bb4a-25c3-4d1d-bfa2-774034a84a17",
                "name": "Salami",
                "allergens": "A,B,C",
                "description": null,
                "grossPrice": 0,
                "tax": 0,
                "isActive": true
              },
              {
                "id": "97952dfe-42ff-45e9-abdd-a7c4371065f9",
                "name": "Schinken",
                "allergens": "A,B,C"
                "description": null,
                "grossPrice": 0,
                "tax": 0,
                "isActive": true
              }
            ]
          }
        ]
      }
    ]
  }
]

Response Structure

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
id	string	false	Unique ID of the article group on the POS
name	string	false	Name of the article group
sort	int	false	order in which the article groups should be sorted (0-n)
fromHour	string	true	limits the timeframe `fromHour` when the article group is available, must be set if `toHour` has a value
toHour	string	true	limits the timeframe `toHour` when the article group is available, must be set if `fromHour` has a value
articles	Array of Article	false	Array of articles in this group

Article Structure

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
id	string	false	Unique ID of the article on the POS
name	string	false	Name of the article
description	string	true	Description of the article
allergens	string	true	Allergene description of the article
grossPrice	int	false	gross price of the article in cent
prices	array of in	false	A optional field to add prices levels to this article. The article price is selected by the `price_level` field set in the Order Type Configuration (Bestell Type Einstellungen)
tax	int	false	tax in percent * 100 for the article
isActive	boolean	false	if the article can be ordered
sort	int	false	order in which the articles are sorted inside the article group
type	int	false	the type of the article, `UNKOWN = 1, OTHER =2, DRINK=3, FOOD=4`
modifiers	Array of Modifiers	false	modifiers for this article
courseGroup	int	false	`0` no course group, `1- 99` valid course group values
tracking	boolean	false	An optional Field. If set to `true` Bessa will track the article amount available for this article. Used to control the `available` field.
available	int	false	An optional Field. The number of articles available to sell, this field is only used if `tracking` is set.

Modifier Structure

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
id	string	false	Unique ID of the modifier on the POS
name	string	false	Name of the modifier
min	int	false	Minimum modifiers the user can select
max	int	false	Maximum modifiers the user can select
ignorePrice	boolean	false	determines if the price of the article has an impact on the order itself.
sort	int	false	order in which the modifiers should be sorted
modifiers	Array of Articles	false	array of articles that belong to this modifier

Menus

Die Artikelgruppen sind teil eines oder mehrere Menüs.

Request

## Article
curl "http://192.168.1.1:8080/treuepass/menus/"

Response

[
  {
    "id": "5eae070f-f62f-4e49-aab8-3588d79ac2eb",´
    "name": "Take-Away Menu",
    "type": 0,
    "groups": [
      "31e04cb2-cb69-4d97-8ec0-6dcaac2b1e85",
      "e400bb4a-25c3-4d1d-bfa2-774034a84a17",
    ]
  },
  {
    "id": "cdde070f-f62f-4e49-aab8-3588d79ac2eb",
    "name": "Dine-In Menu",
    "type": 1,
    "groups": [
      "31e04cb2-cb69-4d97-8ec0-6dcaac2b1e85",
      "e400bb4a-25c3-4d1d-bfa2-774034a84a17",
    ]
  }
]

Response Structure

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
id	string	false	Unique ID of the menu on the POS
name	string	false	Name of the menu
type	int	false	`enum` can be `IN_HOUSE = 0`, `PICKUP = 1`, `DELIVERY = 2`, `KIOSK = 3` , `DISPENSER = 4`, `THIRD_PARTY_PICKUP = 5` , `THIRD_PARTY_DELIVERY = 6` , `KANTEEN = 7`,
groups	Array of string	false	Array of article group ids
ignorePrice	boolean	false	determines if the price of the article has an impact on the order itself.
sort	int	false	order in which the modifiers should be sorted
modifiers	Array of Articles	false	array of articles that belong to this modifier

New Order

Legt eine neue Bestellung in der Kasse ab.

Request

 ## New Order
curl -X "POST" "http://192.168.1.1:8080/treuepass/orders/" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "id": "f7ccfaa0-1949-4058-8854-2078b1a08eb3",
  "items": [
    {
      "article": "5a7dae61-c255-443d-bdd3-1ef25bd448b7",
      "courseGroup": 2,
      "name": "Pizza Salami",
      "amount": 2,
      "grossPrice": 1400,
      "comment": "Bitte ohne Tomaten",
      "modifiers": [
        {
          "name": "Schinken",
          "article": "72283310-e6d9-49b2-9ef9-1b6b13457c0d",
          "grossPrice": 0
        }
      ]
    },
    {
      "article": "5a7dae61-c255-443d-bdd3-1ef25bd448b7",
      "courseGroup": 2,
      "name": "Hauspizza",
      "amount": 1,
      "grossPrice": 500,
      "comment": null,
      "modifiers": []
    }
  ],
  "table": "5eae070f-f62f-4e49-aab8-3588d79ac2eb",
  "orderType": 0,
  "shortOrderId": "5eae070f",
  "time": null,
  "comment": "Bitte schnell, bin hungrig",
  "isAlreadyPaid": true,
  "tip": 150,
  "customer": null,
  "discount": {
  	"discount": 50,
	"article": "5a7dae61-c255-443d-bdd3-1ef25bd448b7"
  },
  service: 0,
  courier: null,
  takeAway: false,
  createdBy: "2.12.0-708-Custom Kiosk",
}'

Customer Example

"customer": {
  "firstName": "Georg",
  "lastName": "Kitz",
  "phone": "123456789",
  "address": {
    "addressLine1": "Luegerstraße 10",
    "postalCode": "9020",
    "city": "Klagenfurt",
    "comment": "Stock 3, 2mal klingen",
  }
}

Request Body

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
id	string	false	The Unique ID of the order on Bessa server
isPickup	boolean	false	deprecated Please use `orderType`
pickupId	string	true	deprecated Please use `orderShortId`
time	string	true	ISO-8601 string representing the order time for pickup or in the future a preorder.
paymentType	PaymentType	false	`enum` can be `CASH = 0`, `ONLINE = 1` , `CREDIT_CARD = 2` , `PAY_PAL = 3` , `BESSA = 4` or `TWINT = 5`
isAlreadyPaid	boolean	false	Determines if the order is to be paid at the venue or if we already collected the payment. Determines if the transaction stays open or if the cashbox should close the transaction right away
print	boolean	false	Determines if a receipt shall be printed
table	string	true	If `orderType == IN_HOUSE` is `true` the `table` must be set.
tip	int	false	The tip in cent
customer	Customer	true	Customer informations
orderType	OrderType	false	`enum` can be `IN_HOUSE = 0`,`PICKUP = 1` , `DELIVERY = 2`, `SELF_SERVICE = 3`, `DISPENSER = 4` or `CANTEEN = 7`
shortOrderId	string	false	is a short version of the `id` and shall be printed, can be a pickup code or some autogenerated number to identify the order for the restaurant and the customer who ordered
deliveryFee	int	true	The delivery fee of the order in cent
packagingFee	int	true	The package fee of the order in cent
serviceFee	int	true	The service calculated for the order, in most cases from third party services like “Lieferando”
items	Array of OrderItem