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, Zahlungen, Stornos und Druckaufträge werden über requests/...-Endpunkte per POST als Auftrag übergeben. Die Kassa verarbeitet den Auftrag und Sie fragen das Ergebnis anschließend ab (siehe Beispiele).

Alle übrigen Ressourcen sind lesend. Die einzige Ausnahme ist customers: Kunden lassen sich synchron anlegen (POST) und ändern (PUT, PATCH). Lagerstände können über die Public API nicht geschrieben werden.

Paginierung

Listen-Endpunkte sind cursorbasiert paginiert. next und previous enthalten jeweils die vollständige URL der benachbarten Seite – inklusive des cursor-Parameters. Die Antwort hat folgende Form:

JSON

{
  "next": "https://api.diekasse.app/v1/public/orders/?cursor=cD0yMDI2LTA2LTE1",
  "previous": null,
  "results": [ ]
}

Rufen Sie die next-URL unverändert auf, bis der Wert null ist, um alle Seiten abzurufen.

Die Antwort enthält keine Gesamtanzahl der Treffer. Wenn Sie eine Summe brauchen, zählen Sie die Seiten selbst mit oder verwenden Sie einen passenden Bericht unter reports/....

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.