Erste Schritte mit der Public API

Diese Seite erklärt, wie Sie Zugang zur bessa Public API erhalten, wie Sie sich authentifizieren und welche Konventionen für alle Endpunkte gelten.

Zugang anfordern

Der Zugang zur Public API wird auf Anfrage freigeschaltet. Wenden Sie sich dazu an bessa bzw. an Ihren Kassenhändler. Nach der Freischaltung steht im bessa Manager ein API-Token für Ihren Mandanten zur Verfügung.

Der Token identifiziert sowohl Ihre Zugangsberechtigung als auch den zugehörigen Mandanten. Behandeln Sie ihn wie ein Passwort und geben Sie ihn nicht weiter.

Authentifizierung

Jede Anfrage wird über einen Authorization-Header mit dem Schlüsselwort Token authentifiziert:

Authorization: Token <ihr-api-token>

Ein eigener Mandanten-Parameter ist nicht nötig – der Mandant wird direkt aus dem Token abgeleitet.

Basis-URL

Alle Endpunkte liegen unter dem folgenden Host und Pfad:

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

Lesen und Einspielen

Die Public API kennt zwei Arten von Zugriffen:

Lesen (synchron): Stammdaten, Belege, Berichte und Lagerstände werden per GET direkt abgefragt.
Einspielen (asynchron): Bestellungen und Zahlungen werden über requests/...-Endpunkte per POST als Auftrag übergeben. Die Kassa verarbeitet den Auftrag und Sie fragen das Ergebnis anschließend ab (siehe Beispiele).

Paginierung

Listen-Endpunkte sind cursorbasiert paginiert. Die Standard-Seitengröße beträgt 25 Einträge; mit limit lässt sie sich anpassen, mit cursor blättern Sie weiter. Die Antwort hat folgende Form:

JSON

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

Folgen Sie dem next-Wert, bis er null ist, um alle Seiten abzurufen.

Datentypen

Beträge werden als Zeichenketten mit zwei Nachkommastellen übertragen (z. B. "19.99").
IDs sind UUIDs (z. B. 550e8400-e29b-41d4-a716-446655440000).
Zeitstempel sind im ISO-8601-Format und in UTC – Details siehe nächster Abschnitt.

Zeitstempel und Zeitzonen

Alle Zeitstempel der API sind in UTC angegeben. Das Z am Ende (z. B. 2026-06-15T15:30:00Z) steht für „Zulu-Zeit", also UTC bzw. den Zeitzonen-Offset +00:00. Österreich liegt im Sommer (MESZ) bei +02:00, im Winter (MEZ) bei +01:00.

Geben Sie in Filtern und Berichtszeiträumen (timestamp__gte, updated__gte, start, end …) immer eine Zeitzone an – entweder mit Z (UTC) oder einem expliziten Offset wie +02:00. Ein Wert ohne Offset wird als UTC interpretiert und kann Ihre Ergebnisse um Ihren lokalen Offset verschieben.

Format und Übergabe: Übergeben Sie immer einen vollständigen ISO-8601-Zeitstempel, nicht nur ein Datum:

in UTC: 2026-06-15T15:30:00Z
mit Offset: 2026-06-15T15:30:00+02:00

In URL-Query-Parametern muss das + eines Offsets als %2B kodiert werden, sonst liest der Server es als Leerzeichen (z. B. ...?start=2026-06-15T00:00:00%2B02:00). Am einfachsten umgehen Sie das, indem Sie den Wert in UTC mit Z übergeben.

Tagesgrenzen: Ein Geschäftstag in lokaler Zeit deckt sich nicht mit einem UTC-Kalendertag. Möchten Sie etwa „den 15. Juni, österreichische Zeit" abfragen, rechnen Sie die lokalen Tagesgrenzen in UTC um:

lokal: 2026-06-15T00:00:00+02:00 bis 2026-06-16T00:00:00+02:00
entspricht in UTC: 2026-06-14T22:00:00Z bis 2026-06-15T22:00:00Z

Eine Abfrage mit dem nackten Datum 2026-06-15 (von der API als UTC-Mitternacht gelesen) würde die späten Abendumsätze des 15. lokal verfehlen und frühe Umsätze des 16. fälschlich einschließen. Wandeln Sie eingehende UTC-Zeitstempel für die Anzeige entsprechend in Ihre lokale Zeitzone zurück.

Fehler und Statuscodes

Status	Bedeutung
`400`	Ungültige Parameter oder ungültiger Anfrage-Body
`401`	Token fehlt oder ist ungültig
`403`	Token gültig, aber keine Berechtigung für die Ressource
`404`	Ressource nicht gefunden

Fehler werden als JSON zurückgegeben:

JSON

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

Bei Validierungsfehlern enthält die Antwort die betroffenen Felder mit den jeweiligen Meldungen.

Vollständige Referenz

Eine vollständige, stets aktuelle Endpunkt-Referenz inklusive aller Felder steht angemeldeten Token-Inhabern als interaktive Oberfläche unter https://api.diekasse.app/v1/public/docs/ zur Verfügung. Einen thematischen Überblick finden Sie unter Verfügbare Ressourcen.