Getting Started with the Public API

This page explains how to get access to the bessa Public API, how to authenticate, and which conventions apply to every endpoint.

Requesting access

Access to the Public API is enabled on request. Please contact bessa or your point-of-sale dealer. Once access is enabled, an API token for your tenant is available in the bessa Manager.

The token identifies both your authorisation and the associated tenant. Treat it like a password and do not share it.

Authentication

Every request is authenticated with an Authorization header using the Token keyword:

Authorization: Token <your-api-token>

A separate tenant parameter is not required – the tenant is derived directly from the token.

Base URL

All endpoints live under the following host and path:

https://api.diekasse.app/v1/public/<resource>/

Reading and pushing

The Public API has two kinds of access:

Reading (synchronous): master data, receipts, reports and stock levels are queried directly with GET.
Pushing (asynchronous): orders and payments are submitted as a job via the requests/... endpoints with POST. The Sales Point processes the job and you query the result afterwards (see Examples).

List endpoints use cursor-based pagination. The default page size is 25 entries; use limit to adjust it and cursor to page through results. The response has the following shape:

JSON

{
  "count": 150,
  "next": "<cursor>",
  "previous": null,
  "results": [ ]
}

Follow the next value until it is null to retrieve all pages.

Data types

Amounts are transmitted as strings with two decimal places (e.g. "19.99").
IDs are UUIDs (e.g. 550e8400-e29b-41d4-a716-446655440000).
Timestamps use the ISO 8601 format and are in UTC – see the next section for details.

Timestamps and time zones

All timestamps in the API are given in UTC. The trailing Z (e.g. 2026-06-15T15:30:00Z) denotes "Zulu time", i.e. UTC, or the time-zone offset +00:00. Austria is at +02:00 in summer (CEST) and +01:00 in winter (CET).

In filters and report periods (timestamp__gte, updated__gte, start, end …) always specify a time zone – either with Z (UTC) or an explicit offset such as +02:00. A value without an offset is interpreted as UTC and can shift your results by your local offset.

Format and how to pass it: Always pass a full ISO 8601 timestamp, not just a date:

in UTC: 2026-06-15T15:30:00Z
with offset: 2026-06-15T15:30:00+02:00

In URL query parameters the + of an offset must be encoded as %2B, otherwise the server reads it as a space (e.g. ...?start=2026-06-15T00:00:00%2B02:00). The easiest way to avoid this is to pass the value in UTC with Z.

Day boundaries: A business day in local time does not coincide with a UTC calendar day. To query, for example, "15 June, Austrian time", convert the local day boundaries to UTC:

local: 2026-06-15T00:00:00+02:00 to 2026-06-16T00:00:00+02:00
equals in UTC: 2026-06-14T22:00:00Z to 2026-06-15T22:00:00Z

A query using the bare date 2026-06-15 (read by the API as UTC midnight) would miss the late-evening local turnover of the 15th and wrongly include early turnover of the 16th. Convert incoming UTC timestamps back to your local time zone for display accordingly.

Errors and status codes

Status	Meaning
`400`	Invalid parameters or request body
`401`	Token missing or invalid
`403`	Token valid, but no permission for the resource
`404`	Resource not found

Errors are returned as JSON:

JSON

{
  "detail": "Authentication credentials were not provided."
}

For validation errors, the response contains the affected fields with their respective messages.

Full reference

A complete, always up-to-date endpoint reference including all fields is available to authenticated token holders as an interactive interface at https://api.diekasse.app/v1/public/docs/. For a thematic overview, see Available Resources.