API

Anmeldung

Jeder Aufruf braucht einen API-Schlüssel im Kopf Authorization. Erzeugt wird er im Portal unter Einstellungen → API-Schlüssel.

curl https://<tenant>.<cluster>.api.bum2.fun/api/v1/artikel \
  -H 'Authorization: Bearer ak_…'

Der Schlüssel wird einmal angezeigt und danach nie wieder; gespeichert ist nur sein SHA-256-Hash. Geht er verloren, legt man einen neuen an und sperrt den alten. Ein Schlüssel kann lesen oder lesen und schreiben — eine Auswertung, die Zahlen abholt, braucht das Schreibrecht nicht.

Nicht als Abfrageparameter mitgeben: der stünde in jedem Zugriffsprotokoll des Webservers, in jedem Proxy und in der Browserhistorie.

Objekte

Sechs Objekte, in dieser Reihenfolge aufeinander aufbauend. Preise, Bestände und Verkäufe verweisen auf Artikel und Standorte — die müssen also zuerst da sein.

Lesen

GET /api/v1/artikel?limit=100&offset=0
GET /api/v1/artikel/100-001

limit geht bis 1000 (Vorgabe 100). Einzeln lesbar sind nur Objekte mit eigener Nummer: store, artikel, kunde, lieferant, verkauf. Preis und Bestand hängen an Artikel und Standort und haben keine eigene — sie kommen über den Artikel.

Schreiben

POST /api/v1/verkauf
Content-Type: application/json

{"daten": [
  {"bonnummer": "2026-0001", "zeitpunkt": "2026-08-15 19:42",
   "storenummer": "RIVA", "artikelnummer": "100-001",
   "menge": 2, "einzelpreis": 33.00}
]}

Kein Vollabgleich

Über die API wird ergänzt und aktualisiert, nie stillgelegt. Ein Vollabgleich, der fehlende Sätze abschaltet, bleibt der Upload-Seite im Portal vorbehalten.

Der Grund ist die Betriebsart: eine Kasse schickt Teilmengen — den Umsatz einer Schicht, die geänderten Preise von heute. Was darin fehlt, ist nicht abgeschafft. Würde die API stilllegen, was sie nicht sieht, legte der erste Aufruf einer Kasse das halbe Sortiment still, und die Antwort wäre ein freundliches 200.

Felder

Aus derselben Beschreibung wie die Excel-Vorlagen. Mit Pflicht gekennzeichnete Felder müssen in jedem Datensatz stehen.

Standorte /api/v1/store

Artikel /api/v1/artikel

Preise /api/v1/preis

Bestände /api/v1/bestand

Kunden /api/v1/kunde

Lieferanten /api/v1/lieferant

Verkäufe /api/v1/verkauf

SAP S/4HANA

Wer Artikel und Preise aus S/4HANA repliziert, muss sie nicht erst in unser Format bringen. Die Bulk-Nachricht ProductMerchandiseViewReplicationBulkRequest wird direkt angenommen — als XML, so wie SAP sie sendet.

POST https://<tenant>.<cluster>.api.bum2.fun/api/v1/sap/produkte?store=RIVA
Content-Type: application/xml
Authorization: Bearer ak_…

Optional ?sprache=DE für die Bezeichnung (Vorgabe DE). Gibt es sie in dieser Sprache nicht, wird die erste vorhandene genommen und das in der Antwort gesagt.

Aus einer Nachricht entstehen zwei Importe: erst die Artikel, dann die Preise. Übernommen wird der Verkaufspreis, der heute gilt — künftige Preise sendet SAP mit, und die gehören noch nicht in die Kasse. Artikel ohne heute gültigen Preis kommen trotzdem an; sie sind an diesem Standort nur nicht im Angebot.

{
  "store": "RIVA",
  "artikel": { "gelesen": 812, "neu": 14, "aktualisiert": 798 },
  "preis":   { "gelesen": 806, "neu": 9,  "aktualisiert": 797 },
  "hinweise": ["6 Artikel ohne heute gültigen Verkaufspreis — Stammdaten übernommen, Preis nicht."]
}

Die Währung wird gegen den Standort geprüft. Weicht sie ab, wird nichts geschrieben: tenant_listung führt keine Währung mit, und 4,40 USD stünden sonst als 4,40 EUR am Regal. Umgerechnet wird nicht — welcher Kurs gilt, ist keine Entscheidung einer Schnittstelle.

Fehler

Nach RFC 9457 (Problem Details) — ein festes Format, damit ein Aufrufer nicht raten muss: title für Menschen, type zum Verzweigen im Code, errors für die Zeilen, die nicht durchkamen.

{
  "type": "https://api.bum2.fun/fehler/anmeldung",
  "title": "Der API-Schlüssel wird nicht angenommen.",
  "status": 401
}

Postman

Eine Sammlung mit allen Aufrufen, erzeugt aus derselben Beschreibung wie diese Seite — sie kann also nicht veralten, solange die Schnittstelle sich nicht ändert.

Sammlung herunterladen

In Postman: Import → Datei wählen. Danach in der Sammlung unter Variables den Wert schluessel auf den eigenen API-Schlüssel setzen; er gilt dann für alle Aufrufe.

Grenzen

Objektkatalog

Die Schnittstelle beschreibt sich selbst — hinter der Anmeldung:

curl https://<tenant>.<cluster>.api.bum2.fun/api/v1/ \
  -H 'Authorization: Bearer ak_…'

Der Katalog steht bewusst hinter der Anmeldung. Er stand einmal davor, und GET /api/v1/ antwortete deshalb mit 200 auch auf einen erfundenen Schlüssel — damit taugte der Endpunkt nicht mehr zum Prüfen der Einrichtung.