Bessa Connector API - English

v30 4.3.2024 - API Version 1.2.11 - en

1 Heartbeat
2 Tables
3 Article
4 Menus
5 New Order
6 Cancel Order
7 Update the POS about new orders

All data is provided by the POS to the connector via a REST server that needs to be implemented by the POS provider. The following document describes all api calls necessary to implement the server. The code snippets assume that the server is reachable at `192.168.1.1:8080/treuepass/`.

Heartbeat

Every 30sec the connector checks the status of the POS and forwards the health check to the Bessa API. This ensures that customers can only order when the connector actually can reach the POS.

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

To ensure in house orders are booked on the correct table, the connector request a list of available tables from the POS.

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

In order to allow customers to order products via the Bessa platform, the connector requests articlegroups, articles and modifiers/options of articles from the POS.

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

The article groups are part of one or more menus.

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`
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

Creates a new order inside the POS.

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
}'

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` or `DISPENSER = 4`
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	false