SmartCubes API Dokumentation

🔐 Authentifizierung

POST /login Anmelden und JWT-Token erhalten Kein Token nötig ▼

Request Body

Feld	Typ	Pflicht	Beschreibung
kundennr	string	✓	z.B. SC-XXXXXXXXXX
mitarbeiterNr	string	✓	z.B. SC-XXXX-XXXX
password	string	✓	Passwort des Mitarbeiters
pushToken	string	–	Expo Push Token (ExponentPushToken[...])
deviceType	string	–	ios / android
deviceName	string	–	Gerätename

Beispiel Request

{
  "kundennr": "SC-XXXXXXXXXX",
  "mitarbeiterNr": "SC-XXXX-XXXX",
  "password": "mitarbeiterpassword"
}

Beispiel Response 200 OK

{
  "success": true,
  "token": "eyJrdW5kZW5uciI6IlNDLTU2OTcwOTk1MDEi...",
  "expiresIn": 86400,
  "user": {
    "id": 1,
    "mitarbeiterNr": "SC-XXXX-XXXX",
    "vorname": "Max",
    "nachname": "Mustermann",
    "rolle": "Admin",
    "kundennr": "SC-XXXXXXXXXX",
    "unternehmen": "Mein Restaurant"
  }
}

GET /health Server-Status prüfen Kein Token nötig ▼

Response

{ "status": "ok", "version": "2.0.0" }

📊 Dashboard

GET /dashboard Tagesstatistiken laden 🔑 Token ▼

Response

{
  "success": true,
  "stats": {
    "mitarbeiter_status": { "total_mitarbeiter": 8, "anwesend": 3, "pause": 1, "urlaub": 1, "krank": 0 },
    "bestellungen": { "gesamt": 24, "neu": 3, "tagesumsatz": 892.50 },
    "reservierungen_heute": 5,
    "aktuelle_gaeste": 12,
    "freie_tische": 8,
    "aktive_rufe": 1,
    "neue_urlaubsantraege": 2
  }
}

🍽️ Speisekarte /menu

GET /menu Speisekarte laden 🔑 Token ▼

Response

{
  "can_edit": true,
  "categories": ["Vorspeisen", "Hauptgerichte", "Getränke"],
  "items": [{ "id": 1, "name": "Schnitzel", "category": "Hauptgerichte", "price": 18.90, "isDrink": false }]
}

POST /menu Kategorie oder Artikel hinzufügen Admin · Filialleitung ▼

{ "action": "add_category", "category_name": "Desserts" }

{
  "action": "add_item",
  "name": "Tiramisu",
  "category": "Desserts",
  "description": "Hausgemacht",
  "price": 7.50,
  "isDrink": false
}

PUT /menu Kategorie oder Artikel bearbeiten Admin · Filialleitung ▼

{
  "action": "update_item",
  "id": 1,
  "name": "Wiener Schnitzel",
  "category": "Hauptgerichte",
  "price": 19.50,
  "isDrink": false
}

{ "action": "update_category", "old_name": "Desserts", "new_name": "Nachspeisen" }

DELETE /menu Kategorie oder Artikel löschen Admin · Filialleitung ▼

{ "action": "delete_item", "id": 1 }

{ "action": "delete_category", "category": "Nachspeisen" }

🧾 Bestellungen /orders

GET /orders Bestellungen laden 🔑 Token ▼

Query Parameter

Parameter	Typ	Default	Werte
status	string	alle	neu · in_bearbeitung · kassenbon · abgeschlossen

Beispiele

# Alle Bestellungen
GET /orders

# Nur neue Bestellungen
GET /orders?status=neu

# Bezahlte Bons
GET /orders?status=kassenbon

POST /orders Neue Bestellung erstellen 🔑 Token ▼

{
  "tischnr": 3,
  "items": [
    { "name": "Schnitzel", "quantity": 2, "price": 18.90 },
    { "name": "Cola", "quantity": 2, "price": 3.50 }
  ]
}

PUT /orders Bestellung aktualisieren 🔑 Token ▼

{ "id": 42, "status": "in_bearbeitung" }

{ "id": 42, "bezahlt": true, "zahlungsart": "bar" }

DELETE /orders Bestellung löschen 🔑 Token ▼

{ "id": 42 }

📅 Reservierungen /reservations

GET /reservations Reservierungen laden 🔑 Token ▼

Query Parameter

Parameter	Default	Werte
status	aktiv	aktiv · storniert · no_show · alle
datum	heute	YYYY-MM-DD

# Aktive Reservierungen heute
GET /reservations

# Für bestimmtes Datum
GET /reservations?datum=2026-03-15&status=aktiv

POST /reservations Neue Reservierung erstellen 🔑 Token ▼

{
  "gast_name": "Familie Müller",
  "datum": "2026-03-15",
  "uhrzeit": "19:00",
  "anzahl_gaeste": 4,
  "tischnr": 5,
  "info": "Fensterplatz gewünscht",
  "farbe": "#3B82F6"
}

PUT /reservations Reservierung ändern oder Status setzen 🔑 Token ▼

{ "id": 10, "action": "confirm" }

{ "id": 10, "action": "cancel", "grund": "Gast hat abgesagt" }

{ "id": 10, "action": "checkin" }

{ "id": 10, "action": "update", "tischnr": 6, "info": "Geburtstag" }

DELETE /reservations Reservierung löschen 🔑 Token ▼

{ "id": 10 }

👥 Mitarbeiter /employees

GET /employees Alle Mitarbeiter laden Admin · Filialleitung ▼

Response (Auszug)

{
  "employees": [{
    "id": 1, "mitarbeiter_nr": "SC-XXXX-XXXX",
    "vorname": "Max", "nachname": "Mustermann",
    "rolle": "Admin", "aktiv": true,
    "status": "Anwesend", "status_color": "success"
  }]
}

POST /employees Neuen Mitarbeiter anlegen Admin · Filialleitung ▼

{
  "vorname": "Anna", "nachname": "Schmidt",
  "email": "anna@restaurant.de",
  "rolle": "Service",
  "position": "Servicekraft",
  "urlaubstage": 30
}
→ Response enthält temp_password für Erstanmeldung

PUT /employees Mitarbeiter bearbeiten Admin · Filialleitung ▼

{ "id": 2, "action": "update", "rolle": "Kasse", "vorname": "Anna" }

{ "id": 2, "action": "reset_password" }
→ Response enthält new_password

{ "id": 2, "action": "toggle_status" }

DELETE /employees Mitarbeiter deaktivieren (nicht löschen) Admin · Filialleitung ▼

{ "id": 2 }

📆 Schichtplan /shifts

GET /shifts?week_start=2026-03-11 Schichtplan für Woche laden 🔑 Token ▼

GET /shifts?week_start=2026-03-11

POST /shifts Schicht erstellen (Einzel oder Serie) Admin · Filialleitung ▼

{
  "action": "single",
  "mitarbeiter_id": 2,
  "datum": "2026-03-15",
  "schicht_start": "08:00",
  "schicht_ende": "16:00",
  "schicht_typ": "Früh"
}

{
  "action": "series",
  "mitarbeiter_id": 2,
  "von_datum": "2026-03-15",
  "bis_datum": "2026-03-21",
  "schicht_start": "08:00",
  "schicht_ende": "16:00",
  "schicht_typ": "Früh"
}
Typen: Früh · Spät · Nacht · Teilzeit · Urlaub · Krank · Frei

PUT /shifts Schicht bearbeiten Admin · Filialleitung ▼

{ "id": 5, "schicht_start": "09:00", "schicht_ende": "17:00" }

DELETE /shifts Schicht löschen Admin · Filialleitung ▼

{ "id": 5 }

🌴 Urlaub /vacation

GET /vacation Urlaubsanträge laden 🔑 Token ▼

GET /vacation?type=my    # Eigene Anträge
GET /vacation?type=all   # Alle (Admin/Filialleitung)

POST /vacation Antrag einreichen / genehmigen / ablehnen 🔑 Token ▼

{ "action": "submit_request", "von_datum": "2026-04-01", "bis_datum": "2026-04-05", "art": "urlaub" }

{ "action": "process_request", "request_id": 3, "status": "genehmigt" }

{ "action": "process_request", "request_id": 3, "status": "abgelehnt", "kommentar": "Zu kurzfristig" }

{ "action": "cancel_request", "request_id": 3 }

⏱️ Zeiterfassung /timetracking

GET /timetracking Zeiterfassung laden 🔑 Token ▼

GET /timetracking?type=today                          # Heutiger Status
GET /timetracking?type=month&month=2026-03            # Monatsübersicht
GET /timetracking?type=overview                       # Gesamtübersicht
GET /timetracking?type=employee&mitarbeiter_id=2      # Einzelner MA

POST /timetracking Stempeln, Pause, Abwesenheit 🔑 Token ▼

{ "action": "clock_in", "mitarbeiter_id": 2 }

{ "action": "clock_out", "mitarbeiter_id": 2 }

{ "action": "pause_start", "mitarbeiter_id": 2 }
{ "action": "pause_end",   "mitarbeiter_id": 2 }

{ "action": "add_absence", "mitarbeiter_id": 2, "datum": "2026-03-15", "typ": "krank" }

DELETE /timetracking Eintrag löschen Admin · Filialleitung ▼

{ "id": 15 }

📦 SmartCubes Hardware /hardware

GET /hardware Alle SmartCubes laden 🔑 Token ▼

{
  "hardware": [{ "id": 1, "tischnr": 3, "helligkeit": 50, "ruf": "inaktiv", "batterie": 85 }],
  "slot_info": { "total_slots": 10, "used_slots": 7, "available_slots": 3 },
  "stats": { "online": 7, "aktive_rufe": 1 }
}

POST /hardware SmartCube hinzufügen oder Aktion ausführen 🔑 Token ▼

{ "tischnr": 8, "helligkeit": 50 }

{ "action": "acknowledge_call", "smartcube_id": 1 }

{ "action": "set_brightness_all", "helligkeit": 75 }

PUT /hardware SmartCube bearbeiten 🔑 Token ▼

{ "id": 1, "tischnr": 4, "helligkeit": 80 }

DELETE /hardware SmartCube entfernen 🔑 Token ▼

{ "id": 1 }

💰 Kassensystem /cash

GET /cash Kassendaten laden 🔑 Token ▼

GET /cash?type=tables                        # Tischübersicht
GET /cash?type=order_details&tischnr=3      # Bestelldetails Tisch 3
GET /cash?type=mitarbeiter                   # MA-Liste für PIN-Login

POST /cash Kassen-Aktionen 🔑 Token ▼

{ "action": "verify_pin", "mitarbeiter_id": 2, "pin": "1234" }

{ "action": "payment", "tischnr": 3, "zahlungsart": "bar", "betrag": 47.80, "gegeben": 50.00, "wechselgeld": 2.20 }

{ "action": "create_reservation", "gast_name": "Tisch 3", "datum": "2026-03-14", "uhrzeit": "20:00", "anzahl_gaeste": 2, "tischnr": 3 }

{ "action": "guest_checkin", "reservation_id": 10 }

{ "action": "deactivate_call", "tischnr": 3 }

🍴 Service / Tischverwaltung /service

GET /service Tische und Bestellungen laden 🔑 Token ▼

GET /service?action=get_tables              # Alle Tische
GET /service?action=get_order&tischnr=3    # Bestellung Tisch 3

POST /service Service-Aktionen 🔑 Token ▼

{ "action": "add_item", "tischnr": 3, "produkt_id": 15, "anzahl": 2, "notizen": "ohne Zwiebeln" }

{ "action": "remove_item", "bestellposition_id": 42 }

{ "action": "close_order", "tischnr": 3, "zahlungsart": "bar", "gegeben": 50.00, "wechselgeld": 2.20 }

{ "action": "acknowledge_call", "tischnr": 3 }
{ "action": "ping_table", "tischnr": 3 }

🖨️ Kassenabschluss /kassenabschluss

POST /kassenabschluss S/T/X/Z-Bon, Kassenstand Admin · Filialleitung ▼

{ "action": "print_x_bon" }

{ "action": "print_z_bon" }
⚠️ Nur 1x pro Tag möglich!

{ "action": "print_s_bon" }

{ "action": "print_t_bon" }

# Kassenstand speichern
{ "action": "save_kassenstand", "ist_bestand": 234.50, "notiz": "Alles korrekt" }

# Kassenstand laden
{ "action": "get_kassenstand" }

# Kassenstand-Bon drucken
{ "action": "print_kassenstand_bon" }

{ "action": "check_z_bon_status" }
{ "action": "check_kassenstand_status" }

👤 Profil /profile

GET /profile Eigenes Profil laden 🔑 Token ▼

GET /profile

POST /profile Profil, Passwort oder PIN ändern 🔑 Token ▼

{ "action": "update_profile", "vorname": "Max", "nachname": "Mustermann", "email": "max@demo.de" }

{ "action": "change_password", "current_password": "alt", "new_password": "neu123", "confirm_password": "neu123" }

{ "action": "change_pin", "current_pin": "1234", "new_pin": "5678", "confirm_pin": "5678" }

{ "action": "reset_pin", "password": "meinPasswort" }

⚙️ Einstellungen

GETPOST /settings Kassen-Einstellungen Admin · Filialleitung ▼

# Speichern
{ "action": "save_settings", "auto_lock_minutes": 5, "sound_enabled": true, "cloudprnt_enabled": true, "printer_mac": "AA:BB:CC:DD:EE:FF" }

# Testdruck
{ "action": "test_cloudprnt", "printer_mac": "AA:BB:CC:DD:EE:FF", "printer_name": "Bondrucker" }

GETPOST /restaurant Restaurant-Stammdaten & Öffnungszeiten Admin ▼

# Infos speichern
{ "action": "save_info", "restaurantname": "Mein Restaurant", "plz": "75172", "ort": "Pforzheim", "ustid": "DE123456789" }

# Öffnungszeiten speichern
{ "action": "save_opening_hours", "opening_hours": { "montag": { "offen": true, "von": "11:00", "bis": "22:00" } } }

GETPOST /kassenbon-settings Kassenbon Logo, QR, Öffnungszeiten Admin · Filialleitung ▼

{ "action": "save_settings", "logo_enabled": true, "qr_enabled": true, "qr_url": "https://mein-restaurant.de", "opening_hours_mode": "today" }

GETPOST /reservation-settings Auto-Cancel Einstellungen Admin · Filialleitung ▼

{ "action": "save_settings", "auto_cancel_enabled": true, "auto_cancel_minutes": 30 }

GETPOST /payment-methods Zahlungsmethoden konfigurieren Admin ▼

{ "action": "save_payment_method", "method": "karte", "enabled": true, "config": {} }
Methoden: bar · karte · paypal · stripe · stripe_terminal

GETPOST /printer-settings Bluetooth + CloudPRNT Drucker Admin · Filialleitung ▼

{ "action": "save_settings", "cloudprnt_enabled": true, "cloudprnt_printer_mac": "AA:BB:CC:DD:EE:FF" }
{ "action": "test_cloudprnt", "printer_mac": "AA:BB:CC:DD:EE:FF" }

📄 Verträge & Rechnungen

GETPOST /contracts Verträge verwalten 🔑 Token ▼

# Hardware bestellen
{ "action": "order_hardware", "anzahl": 5 }

# Kündigen
{ "action": "cancel_contract", "contract_id": 1 }

# Reaktivieren
{ "action": "reactivate_contract", "contract_id": 1 }

GETPUT /invoices Rechnungen laden und Status ändern 🔑 Token ▼

GET /invoices                   # Alle Rechnungen
GET /invoices/pdf?invoice_id=5  # PDF Download

# Status ändern (PUT)
{ "id": 5, "status": "Bezahlt" }

GETPOST /payment-data Bankverbindung / SEPA Admin ▼

{ "kontoinhaber": "Max Mustermann", "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "sepa_mandat": true, "abrechnungstag": 1 }

🔒 TSE & Steuer-Export

GETPOST /tse-config Fiskaly TSE konfigurieren Admin · Filialleitung ▼

# Verbindung testen
{ "action": "test_connection" }

# TSS erstellen (vollautomatisch)
{ "action": "create_tss", "tss_id": "meine-tss-id", "description": "SmartCube TSS" }

# TSS initialisieren
{ "action": "initialize_tss" }

# Client anlegen
{ "action": "create_client", "client_id": "client-001", "serial_number": "SmartCube-001" }

# Status abrufen
{ "action": "get_status" }

GETPOST /dsfinvk DSFinV-K Export Admin · Filialleitung ▼

GET /dsfinvk?action=list
GET /dsfinvk?action=status&export_id=abc-123
GET /dsfinvk?action=download&export_id=abc-123  → TAR Download

# Export starten (POST)
{ "action": "start_export", "start_date": "2026-03-01", "end_date": "2026-03-31" }

GETPOST /tse-tar TSE TAR Export Admin · Filialleitung ▼

GET /tse-tar?action=list
GET /tse-tar?action=status&export_id=abc-123

# Kompletter Export (POST)
{ "action": "start_export" }

# Zeitraum-Export (POST)
{ "action": "start_export", "start_date": "2026-03-01", "end_date": "2026-03-31" }

GETPOST /datev DATEV cashregister Import Admin · Filialleitung ▼

GET /datev?action=list
GET /datev?action=status&import_id=42

# Import starten (POST)
{ "action": "start_import", "start_date": "2026-03-01", "end_date": "2026-03-31", "sandbox": true }

📈 Statistiken

GET /tischauslastung Tischauslastung & Verweildauer 🔑 Token ▼

GET /tischauslastung?zeitraum=day    # Heute
GET /tischauslastung?zeitraum=week   # Diese Woche
GET /tischauslastung?zeitraum=month  # Dieser Monat

Response

{
  "stats": { "auslastung_prozent": 60.0, "belegte_tische": 6, "umsatz_gesamt": 634.50 },
  "tische": [{ "tischnr": 3, "umsatz": 187.60, "avg_verweildauer_min": 52.5 }],
  "hourly": [{ "stunde": 12, "tische": 3, "bestellungen": 5 }]
}

GET /umsatz Umsatz-Statistik mit Mitarbeiter-Vergleich 🔑 Token ▼

GET /umsatz?zeitraum=day|week|month

Response

{
  "totals": { "umsatz_gesamt": 892.50, "umsatz_bar": 534.00, "umsatz_ec": 358.50, "stornos": 1 },
  "top_items": [{ "name": "Schnitzel", "menge": 12, "umsatz": 226.80 }],
  "mitarbeiter": [{ "name": "Max M.", "bestellungen": 15, "umsatz": 567.00 }],
  "daily": [{ "datum": "2026-03-14", "umsatz": 892.50 }]
}

GET /wartezeiten Wartezeiten & P-Smart Score 🔑 Token ▼

GET /wartezeiten?zeitraum=day|week|month

Response

{
  "stats": { "avg_wartezeit_min": 12.5, "psmart_score": 87.5 },
  "verteilung": { "unter_5min": 3, "von_5_15min": 14, "von_15_30min": 6, "ueber_30min": 1 },
  "ausreisser": [{ "tischnr": 7, "wartezeit_min": 38 }]
}

⚠️ Fehlercodes

Code	Bedeutung	Ursache
200	OK	Erfolgreich
201	Created	Ressource wurde erstellt
400	Bad Request	Fehlende oder ungültige Felder
401	Unauthorized	Kein Token / Token abgelaufen
403	Forbidden	Falsche Rolle / keine Berechtigung
404	Not Found	Ressource nicht gefunden
500	Internal Server Error	Serverfehler / DB-Fehler
502	Bad Gateway	Externer API-Fehler (Fiskaly, DATEV)

# Fehler-Response Format:
{ "detail": "Fehlermeldung hier" }