Developer-Dokumentation

APRO ist die modulare Kassenplattform für Restaurant, Hotel, Foodtruck oder Systemgastronomie — offen für alles, was du brauchst. Von Hotelsoftware über Buchhaltung, Zahlungs- und Zutrittssysteme bis zu Reservierungs- und Lieferdiensten: APRO verbindet sich nahtlos mit deiner bestehenden Systemlandschaft, für durchgängige Prozesse und maximalen Automatisierungskomfort.

Diese Seite richtet sich an Entwicklungsteams, die auf dieser Oberfläche aufbauen: Partner mit Reservierungs- oder Warenwirtschaftssystemen, Lieferplattformen, die Bestellungen in die Kassa einsteuern, BI-Tools mit Lesezugriff auf den Belegbestand oder interne Teams, die Reports automatisieren.

Was Sie hier finden

• REST-APIs. Stabile JSON-über-HTTPS-Endpunkte für die unten genannten Bereiche. Jeder Endpunkt wird über einen einzigen API-Key authentifiziert — kein SDK erforderlich, kein OAuth-Flow zu orchestrieren.
• SQL-Views. Lesende Views für direkten Datenbankzugriff, ideal für BI-Pipelines und Data Warehouses.
• Payload-Beispiele. Jedes Beispiel auf dieser Seite liegt zusätzlich als eigenständige JSON-Datei unter /samples/ vor und kann direkt heruntergeladen und abgespielt werden.
• Vollständige API-Referenz. Der maschinenlesbare Vertrag ist unter api-docs.apro.at veröffentlicht.

Wählen Sie Ihren Einstieg

Status und Versionierung

Endpunkte unter /api/v1/… gelten als stabil. Breaking Changes werden in den Release Notes auf apro.at angekündigt. Neue optionale Felder und nicht-brechende Ergänzungen in Antworten können jederzeit dazu kommen — Parser sollten unbekannte Keys tolerieren.

Support

• Vertrieb & Onboarding: apro.at/support
• Integrationsfragen: über Ihre APRO-Ansprechperson.

Alle APRO-REST-Endpunkte verwenden einen einzigen API-Key, übergeben im Request-Header x-api-key. Es gibt keinen OAuth-Flow und kein Token-Refresh — Keys sind langlebig und auf einen Mandanten oder einen einzelnen Standort beschränkt.

Header

POST /api/v1/external/order HTTP/1.1
Host: my.apro.at
x-api-key: sk_live_pLpXZq8S…
content-type: application/json

Key-Scope

Jeder APRO-REST-Key ist an einen Standort gebunden. Ein Request ist nur erfolgreich, wenn der aus dem Endpunkt abgeleitete Standort mit dem Standort des Keys übereinstimmt.

Ein standortgebundener Key versagt sicher, wenn er gegen einen anderen Standort verwendet wird, und ist unbedenklich an Partner oder ein einzelnes Deployment weiterzugeben.

Key beziehen

Keys werden vom APRO Account-Team ausgestellt. Anfrage an Ihre Ansprechperson oder an apro.at/support. Rotation wird unterstützt; der abgelöste Key bleibt eine Karenzzeit lang gültig, damit Sie ohne Ausfall umziehen können.

Keys aufbewahren

• Niemals in das Versionskontrollsystem einchecken.
• Keys in einem Secret Manager speichern (Azure Key Vault, 1Password, HashiCorp Vault, GitHub-Actions- oder Azure-DevOps-Secrets).
• Zur Laufzeit als Umgebungsvariable (APRO_API_KEY) einspielen.

Fehlerantworten

Die Umsatz-API liefert alle umsatzrelevanten Transaktionen eines Zeitraums — samt Positionen, Zahlungen und Steueraufteilung — in einer einzigen Abfrage. Ideal für Buchhaltungsexporte, Umsatzabstimmung, BI-Warehouses oder Ad-hoc-Reports.

Tipp: Umsatz API oder SQL Views?
Die Umsatz-API und die SQL Views liefern
dieselben Daten in unterschiedlicher Form für unterschiedliche
Laufzeiten:

- Umsatz API — über den öffentlichen Cloud-Endpunkt
(my.apro.at). Pro Beleg ein hierarchisches JSON-Objekt mit
Positionen, Zahlungen, Steuersätzen, Bediener und Tisch bereits
verschachtelt. Ideal für Off-Premise-Systeme, SaaS-Integrationen,
Mobile Clients — überall, wo ein fertiger Objektbaum gewünscht ist.
- SQL Views — lesende Views direkt auf der
On-Premise-Kassendatenbank. Flach, relational, mit jedem
SQL-Server-fähigen Tool abfragbar. Ideal für On-Premise-
Integrationen, ETL-Pipelines und **bestehende BI-Workflows
(Power BI, Tableau, Qlik, Metabase)**.

Cloud-API für Realtime-System-zu-System-Integration, SQL-Views für
Bulk-Analytics und Dashboards.

• Host: my.apro.at
• Auth: API-Key im x-api-key
• Content type: application/json

Endpunkte

Beide Varianten erfordern einen standortgebundenen API-Key. Der Key selbst bestimmt, welche Standortdaten geliefert werden — einen mandantenweiten Endpunkt gibt es nicht. Wähle, was im Client-Code klarer ist — beide liefern dieselben Daten und benötigen denselben Key.

Request-Body

Beispielanfrage

POST /api/v1/reports/receipts

{
  "after":  "2026-01-01T00:00:00Z",
  "before": "2026-02-01T00:00:00Z",
  "limit":  100,
  "afterTransactionID": "f03e11de-6330-4a03-a8a8-b6e5fd4e32a5"
}

Download: revenue-request.json

Antwort

Ein Array von Belegen. Jedes Element ist eine Transaktion mit Positionen, Zahlungen und Metadaten.

Top-Level-Felder

Item

Side dish

Unterartikel sind die Beilagen und Modifikatoren, die unter einer Position gebucht werden — die Pommes zum Schnitzel, das ohne Zwiebel zum Burger. Sie werden verschachtelt in der übergeordneten Position zurückgegeben, nie als eigene Positionen.

Ein Unterartikel nutzt dieselbe Item-Struktur, befüllt aber nur die folgenden Felder. Alle übrigen — bookDate, externalId, purchasePrice, course, tax, category, sideDishes — sind null bzw. ihr Default-Wert; Unterartikel verschachteln sich nicht rekursiv.

Achtung: Unterartikel nicht zu den Summen addieren
Ein Unterartikel mit Aufpreis ist **bereits im grossAmount /
netAmount der übergeordneten Position** und im totalAmount des
Belegs enthalten. Wer sideDishes[].grossAmount zusätzlich aufaddiert,
zählt Umsatz doppelt. Die Beträge sind eine Aufschlüsselung für die
Anzeige, keine eigenständigen Positionen.

sideDishes ist null — nicht [] — wenn eine Position keine Unterartikel hat, ebenso bei älteren Query-Konfigurationen aus der Zeit vor diesem Feature. Daher auf null-oder-leer prüfen, statt ein Array vorauszusetzen.

Tax

Category

Payment

Payment type

Business

Staff

Table

Location

Area

Der Bereich bzw. die Zone, in der ein Tisch steht.

Payment group

Die Gruppierung, in der die Zahlungsarten zusammenlaufen — für Kassabuch- und Abschluss-Auswertungen.

Customer

Hinweis: Aktuell immer null
Der Receipts-Endpunkt befüllt customer nicht — das Feld ist im
Response-Contract reserviert, wird von der Abfrage aber nicht gesetzt.
Keine Rechnungsempfänger-Logik darauf aufbauen; Kunden stattdessen über
die eigenen Endpunkte auflösen.

Beispielantwort

Response · zwei direkt aufeinanderfolgende Abrechnungen

[
  {
    "transactionId": "f03e11de-6330-4a03-a8a8-b6e5fd4e32a5",
    "transactionType": "Abrechnen",
    "receiptType": "Beleg",
    "totalAmount": 3.2,
    "tip": 0.0,
    "discount": 0.0,
    "dateTime": "03.10.2021 21:59:57",
    "business": { "id": "1", "name": "APRO Kassensysteme" },
    "location": { "id": "7236", "name": "Wien Haupthaus" },
    "staff":    { "id": "8", "number": 9500, "name": "Onlinekellner" },
    "table":    { "id": "76", "number": 76, "name": "Daniel Z" },
    "area":     { "id": "3", "number": 3, "name": "Garten" },
    "customer": null,
    "paymentGroup": { "id": 2, "name": "Kartenzahlung" },
    "payments": [
      {
        "id": "04b2d2f5-8765-41b5-ad5c-aed802dc23bc",
        "amount": 3.2,
        "paymentType": { "id": 26, "nr": 200, "name": "Smorder Kreditkarte" },
        "fibuAccountNr": "2751"
      }
    ],
    "items": [
      {
        "id": "38",
        "number": 216,
        "name": "Wiener Schnitzel",
        "uniqueId": "0f6c2c14-3f8a-4f0b-9a1e-2b7d5c8e4411",
        "externalId": null,
        "bookDate": "03.10.2021 21:59:55",
        "grossAmount": 3.2,
        "netAmount": 3.2,
        "purchasePrice": 1.1,
        "quantity": 1.0,
        "course": 2,
        "tax": { "id": "5", "value": 5.0, "name": "Mwst 5 %" },
        "category": { "id": "12", "number": 12, "name": "Hauptspeisen" },
        "sideDishes": [
          {
            "id": "512",
            "number": 9001,
            "name": "Pommes",
            "uniqueId": "b41d9a77-55c2-4e3d-8f10-6cc0a2b93d88",
            "grossAmount": 1.5,
            "netAmount": 1.36,
            "quantity": 1.0
          },
          {
            "id": "518",
            "number": 9007,
            "name": "ohne Zwiebel",
            "uniqueId": "c9a70e31-1d44-4a92-b7e5-30f8c1d6a204",
            "grossAmount": 0.0,
            "netAmount": 0.0,
            "quantity": 1.0
          }
        ]
      }
    ],
    "guestCount": 2
  },
  {
    "transactionId": "db2b90d1-ab37-4557-b169-2289c3004a0a",
    "transactionType": "Abrechnen",
    "receiptType": "Beleg",
    "totalAmount": 3.2,
    "tip": 0.0,
    "discount": 0.0,
    "dateTime": "03.10.2021 22:00:12",
    "business": { "id": "1", "name": "APRO Kassensysteme" },
    "location": { "id": "7236", "name": "Wien Haupthaus" },
    "staff":    { "id": "8", "number": 9500, "name": "Onlinekellner" },
    "table":    { "id": "76", "number": 76, "name": "Daniel Z" },
    "area":     { "id": "3", "number": 3, "name": "Garten" },
    "customer": null,
    "paymentGroup": { "id": 2, "name": "Kartenzahlung" },
    "payments": [
      {
        "id": "bb3e6300-0cc3-4922-80c4-a8a4c3530d3c",
        "amount": 3.2,
        "paymentType": { "id": 26, "nr": 200, "name": "Smorder Kreditkarte" },
        "fibuAccountNr": "2751"
      }
    ],
    "items": [
      {
        "id": "38",
        "number": 216,
        "name": "Cola 0,5",
        "uniqueId": "7d2f3b90-6c11-4c8e-93aa-5e4419c7f0d3",
        "externalId": null,
        "bookDate": "03.10.2021 22:00:11",
        "grossAmount": 3.2,
        "netAmount": 3.2,
        "purchasePrice": 0.7,
        "quantity": 1.0,
        "course": null,
        "tax": { "id": "5", "value": 5.0, "name": "Mwst 5 %" },
        "category": { "id": "20", "number": 20, "name": "Alkoholfreie Getränke" },
        "sideDishes": null
      }
    ],
    "guestCount": 1
  }
]

Dieselbe Payload als eigenständige Datei herunterladen: revenue-response.json

Transaktionstypen

Der transactionType unterscheidet, was eine Zeile repräsentiert. Für umsatzrelevante Reports auf Abrechnen filtern (und RechnungZurückholen für Rückholungen).

Umsatzberechnung

Um den umsatzrelevanten Umsatz einer Antwort zu berechnen, behält man bezahlte Abrechnungen samt Rückholungen und summiert die Netto-Positionen:

response
  .filter(x =>
    x.paymentGroup.name === "Umsatzwirksam" &&
    ["Abrechnen", "RechnungZurückholen"].includes(x.transactionType)
  )
  .map(x =>
    x.items.reduce((sum, item) => sum + item.netAmount * item.quantity, 0)
  )
  .reduce((sum, val) => sum + val, 0);

Paging

Es gibt keinen Cursor in der Antwort — nutzen Sie die deterministische transactionId der zuletzt gesehenen Zeile als afterTransactionID der nächsten Anfrage, after/before bleiben unverändert. So lange iterieren, bis die Antwort weniger Zeilen liefert als Ihr limit.

Fehler

Siehe Authentifizierung → Fehlerantworten.

Die Externe-Bestellung-API nimmt eine vollständig formulierte Bestellung aus einem beliebigen Fremdsystem entgegen — Lieferaggregator, White-Label- App, Kiosk, Voice-Agent — und steuert sie in die laufende APRO-Kassa am Zielstandort ein. Ein einziger POST genügt; die Bestellung erscheint sofort im Bestellmanager.

• Endpunkt: POST https://my.apro.at/api/v1/external/order
• Auth: API-Key im x-api-key
• Content type: application/json

Bestellung einem Standort zuordnen

Die Bestellung muss genau einem Standort zugeordnet sein. Geben Sie einen der folgenden Werte mit — der erste nicht-leere Wert gewinnt:

1. LocationID — numerische ID
2. LocationShortCode — Kurz-Identifier (z. B. vienna-main)
3. SpotID — konkreter Tisch/Zimmer/Abholpunkt (Standort wird abgeleitet)
4. QRCode — gescannter APRO-QR-Code (Standort und Spot werden abgeleitet)

Fehlen alle, wird die Anfrage abgelehnt.

Request-Body

Entry

Addon

UserInfo

DeliveryInfo

Beispiele

Minimalbestellung

POST /api/v1/external/order

{
  "locationShortCode": "vienna-main",
  "takeaway": true,
  "userInfo": { "email": "guest@example.com" },
  "entries": [{ "productNr": "123", "quantity": 1 }],
  "grandTotal": 9.99
}

Download: external-order-minimal.json

Vollständige Bestellung mit Lieferung und Beilagen

POST /api/v1/external/order

{
  "guid": "123e4567-e89b-12d3-a456-426614174000",
  "locationId": 101,
  "spotId": 15,
  "spotNumber": 10,
  "shortCode": "zw1356",
  "userInfo": {
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "max.mustermann@example.com",
    "phone": "+491234567890",
    "locale": "de-DE",
    "nickname": "Max"
  },
  "takeaway": false,
  "note": "Bitte schnell liefern",
  "qrCode": "QR1234567890",
  "deliveryInfo": {
    "name": "Max Mustermann",
    "city": "Wien",
    "zip": "1010",
    "street": "Stephansplatz 1",
    "country": "AT",
    "floor": "3",
    "stairway": "A",
    "door": "12"
  },
  "entries": [
    {
      "productNr": "123",
      "name": "Wiener Schnitzel",
      "quantity": 2,
      "price": 9.99,
      "note": "Extra scharf",
      "addons": [
        { "productNr": "501", "name": "Pommes", "quantity": 2, "price": 3.5 }
      ]
    },
    { "productNr": "31231", "name": "Burger Classic", "quantity": 1, "note": "Ohne Zwiebeln" }
  ],
  "preOrderTime": 1723574400000,
  "tip": 1.2,
  "isPaid": true,
  "grandTotal": 28.18
}

Download: external-order-full.json

Idempotenz

Setzen Sie guid immer auf eine stabile, client-generierte UUID. APRO nutzt sie zur Deduplizierung bei Retries — geht eine Antwort verloren und Sie senden erneut, ist der zweite POST ein No-Op und liefert Erfolg.

Preisberechnung

APRO berechnet jede Position serverseitig aus productNr neu. price auf einem Entry oder Addon greift nur, wenn explizit übergeben; grandTotal wird mit dem Server-Total abgeglichen, inkonsistente Payloads werden abgelehnt. So wird der Wert zugleich Sicherheitsnetz und Vehikel für Kampagnen-Rabatte.

Der Externe-Katalog-API bietet eine schlanke, nur lesende Sicht auf die Stammdaten eines APRO-Standorts — Artikel, Warengruppen und Spots (Tische, Zimmer, Abholpunkte) — zur Verwendung in White-Label- Apps, Kiosks, externen Speisekarten und Partnerintegrationen.

Die drei Endpunkte teilen sich dieselben Konventionen: Scope per Standort, verschachtelte DTO-Struktur, Filterung über Query-Parameter und Paginierung.

• Host: my.apro.at
• Auth: API-Key im x-api-key
• Content type: application/json

Tipp: In Postman ausprobieren
Lade die fertige Collection herunter:
apro-external-catalog.postman_collection.json.
In Postman importieren, im Variables-Tab der Collection apiKey und
locationShortCode setzen, dann Send drücken.

Achtung: Filter verwenden eine Bracket-Syntax
Alle Filterfelder — inklusive des Pflichtfeldes locationId /
locationShortCode — müssen als filter['<name>']=<value> übergeben
werden, nicht als gewöhnliche Query-Parameter. Schlichtes
?locationShortCode=… wird stillschweigend ignoriert; die Anfrage
schlägt dann mit „location not resolved" fehl. Details unter
Filterung.

Endpunkte

Gemeinsame Konventionen

Standort-Scope

Jede Anfrage muss genau einen Standort adressieren. Geben Sie einen der folgenden Werte mit:

1. locationId — numerische ID
2. locationShortCode — Kurz-Identifier (z. B. vienna-main)

Lässt sich aus keinem von beiden ein Standort auflösen, wird die Anfrage mit 400 Bad Request abgelehnt.

Paginierung

Jede Antwort steckt in einem Paged-Envelope:

{
  "page": { "offset": 0, "limit": 50, "total": 1234 },
  "data": [ /* ... */ ]
}

• offset und limit spiegeln die Anfrage.
• total ist die Gesamtanzahl aller passenden Datensätze über alle Seiten — Grundlage für skip/take-Schleifen.

Filterung

Filter werden als bracketed Query-Parameter unter dem Schlüssel filter übergeben — filter['<name>']=<value>. Schlichtes ?<name>=<value> wird ignoriert. Paginierung (skip, take) bleibt als gewöhnliche Query-Parameter.

Listen-Filter (productIds, gtins, externalSpotIds, …) werden kommagetrennt übergeben. Literale Kommas mit \, escapen.

GET /api/v1/external/product?filter['locationShortCode']=vienna-main
  &filter['productNrs']=A-100,A-200
  &filter['isVisible']=true
  &filter['search']=schnitzel
  &skip=0&take=100

Hinweise:

• Der Klammer-Key ist case-insensitive — filter['LocationShortCode'] und filter['locationShortCode'] sind äquivalent.
• filter["…"] (doppelte Anführungszeichen, URL-kodiert als %22) funktioniert ebenfalls.
• Unbekannte Filterparameter werden ignoriert.

Artikel

GET https://my.apro.at/api/v1/external/product

Query-Parameter

Product

Pricing

ProductCashbox

Media

Flags

Nutrition

Ingredient

NutritionalValue

Localization

name, subtitle, description und media.imageUrl auf oberster Ebene enthalten weiterhin die Standardwerte (Deutsch) — localizations ersetzt sie nicht, sondern ergänzt nur die vorhandenen Übersetzungen. Einträge ohne Sprachschlüssel werden weggelassen, und einzelne Felder eines Eintrags können null sein, wenn genau dieser Text nicht übersetzt wurde. Zur Anzeige die gewünschte Sprache in localizations suchen und auf das Feld der obersten Ebene zurückfallen.

Beispiel

GET /api/v1/external/product?filter['locationShortCode']=vienna-main&filter['isVisible']=true&take=2

{
  "page": { "offset": 0, "limit": 2, "total": 1247 },
  "data": [
    {
      "id": 9001,
      "productNr": "A-100",
      "gtin": "9001234567890",
      "externalProductId": "wiener-schnitzel",
      "name": "Wiener Schnitzel",
      "externalName": "Wiener Schnitzel",
      "subtitle": "Mit Erdäpfelsalat",
      "description": "Klassisches Wiener Schnitzel vom Kalb.",
      "pricing": {
        "defaultPrice": 22.9,
        "referencePrice": null,
        "taxRateId": 3,
        "allowClientPrice": false
      },
      "cashbox": { "cashboxId": 17, "productionPlaceId": 2, "parentProductId": null },
      "media": { "imageUrl": "https://cdn.smorder.at/locations/7236/p/9001.jpg" },
      "flags": { "isVisible": true, "isLocked": false, "queuedForReview": false },
      "nutrition": {
        "amount": 250,
        "amountUnit": "g",
        "calories": 720,
        "allergens": 67,
        "minimumAge": 0,
        "ingredients": [{ "name": "Kalb" }, { "name": "Weizenmehl" }, { "name": "Ei" }],
        "nutritionalValues": [
          { "name": "Gewicht", "unit": "g", "value": "250", "belongsTo": null },
          { "name": "Fett",    "unit": "g", "value": "30",  "belongsTo": null }
        ]
      },
      "productGroupExternalIds": ["mains", "austrian"],
      "localizations": [
        {
          "locale": "en",
          "name": "Viennese Schnitzel",
          "subtitle": "With potato salad",
          "description": "Classic Viennese veal schnitzel.",
          "imageUrl": null
        },
        {
          "locale": "it",
          "name": "Cotoletta alla viennese",
          "subtitle": null,
          "description": null,
          "imageUrl": null
        }
      ]
    }
  ]
}

Download: external-products-response.json

Warengruppen

GET https://my.apro.at/api/v1/external/product-category

Warengruppen entsprechen den APRO Product Groups — die kassenbezogene Gruppierung, die Reports, Steuersätze und Druckreihenfolge steuert. Das Feld productGroupExternalIds auf einem Artikel referenziert genau die externalId, die hier zurückkommt — damit lassen sich beide Antworten ohne zusätzliche Lookups verbinden.

Query-Parameter

ProductCategory

CategoryCashbox

CategoryTax

CategoryLocalization

Es gelten dieselben Regeln wie bei Artikeln: name auf oberster Ebene bleibt der deutsche Standardwert, localizations ergänzt nur das, was vorhanden ist.

Beispiel

GET /api/v1/external/product-category?filter['locationShortCode']=vienna-main

{
  "page": { "offset": 0, "limit": 50, "total": 14 },
  "data": [
    {
      "id": 41,
      "externalId": "mains",
      "name": "Hauptspeisen",
      "externalName": "Mains",
      "cashbox": { "cashboxId": 17, "supplierId": null },
      "tax": { "taxRateId": 3, "vat": 10 },
      "localizations": [
        { "locale": "en", "name": "Mains", "description": null, "imageUrl": null },
        { "locale": "it", "name": "Secondi", "description": null, "imageUrl": null }
      ]
    },
    {
      "id": 42,
      "externalId": "drinks-alcoholic",
      "name": "Getränke (Alkohol)",
      "externalName": "Alcoholic drinks",
      "cashbox": { "cashboxId": 17, "supplierId": null },
      "tax": { "taxRateId": 1, "vat": 20 },
      "localizations": []
    }
  ]
}

Download: external-product-categories-response.json

Spots

GET https://my.apro.at/api/v1/external/spot

Spots sind die physischen / logischen Ziele, an die ein Gast bestellen kann: Tische, Zimmer, Abholtheken, Lieferzonen, Drive-in.

Query-Parameter

Spot

SpotLocation

SpotArea

SpotGeo

SpotFlags

Beispiel

GET /api/v1/external/spot?filter['locationShortCode']=vienna-main&filter['type']=Table&filter['visibleInApp']=true&take=2

{
  "page": { "offset": 0, "limit": 2, "total": 38 },
  "data": [
    {
      "id": 1501,
      "externalSpotId": "table-01",
      "number": 1,
      "name": "Tisch 1",
      "alternativeName": null,
      "description": null,
      "qrCode": "QR-01",
      "type": "Table",
      "capacity": 4,
      "location": { "locationId": 7236, "locationShortCode": "vienna-main" },
      "area": { "areaId": 11, "name": "Gastgarten", "externalAreaId": "garden" },
      "geo": null,
      "flags": {
        "visibleInApp": true,
        "supportsTableOrder": true,
        "supportsCashPayment": true,
        "defaultToTakeAway": false,
        "displayAsButton": false
      }
    }
  ]
}

Download: external-spots-response.json

Cross-API-Joins

Die drei Endpunkte sind so geschnitten, dass sie sich client-seitig verbinden lassen:

• product.productNr ↔ productNr (Entry / Addon) der Externe-Bestellung-API — case-insensitive, gematcht ausschließlich gegen Artikel auf der Primär-Kassa des Standorts. Wenn productNr nicht auflöst, greift im Bestell-Pipeline ein Fallback über den name-Wert des Entries gegen product.name.
• product.productGroupExternalIds[i] ↔ productCategory.externalId
• product.cashbox.cashboxId / productCategory.cashbox.cashboxId ↔ cashboxId-Filter auf beiden Endpunkten
• spot.location.locationShortCode ↔ locationShortCode-Filter überall
• spot.id ↔ SpotID der External-Order-API — die id des Spots direkt zurückgeben, um eine Bestellung an denselben Spot zurückzurouten, von dem sie gelesen wurde. spot.qrCode entspricht dem QRCode-Feld der External-Order-API.

Fehler

Die Menükarten-API liefert die öffentliche Menüstruktur für White-Label-Apps, Selbstbedienungskiosks und QR-Ordering-Flows. Das Lesen erfordert keine Authentifizierung; jede schreibende Aktion schon.

• Host: my.apro.at
• Content type: application/json

Menü abrufen

GET https://my.apro.at/api/v1/locations/{locationId}/menus

• Auth: nein
• Beispiel: my.apro.at/api/v1/locations/7236/menus

Die Antwort ist ein Baum. Ebenen von außen nach innen:

1. Menu — oberste Gruppierung (z. B. Speisen, Getränke, Angebote).
2. Category — Abschnitt innerhalb eines Menüs (z. B. Hauptspeisen).
3. MenuEntry — konkreter verkaufbarer Artikel.
4. MenuEntryFeature — Beilagen-/Modifier-Gruppe zu einem Artikel.
5. MenuEntryFeatureValue — einzelne Option innerhalb einer Gruppe.
6. Hours — Gültigkeitsfenster, die an Menüs und Kategorien hängen.

Beispielantwort (gekürzt)

GET /api/v1/locations/{locationId}/menus

[
  {
    "name": "Speisen",
    "badge": 7,
    "imageUrl": "https://cdn.smorder.at/locations/7236/menus/speisen.jpg",
    "description": "Klassiker aus der österreichischen Küche.",
    "priceName": "Hauspreis",
    "orderableHours": [
      { "days": 254, "startTime": "11:00", "endTime": "22:00" }
    ],
    "categories": [
      {
        "name": "Hauptspeisen",
        "menuEntries": [
          {
            "menuEntryID": 4001,
            "name": "Wiener Schnitzel",
            "badge": 7,
            "price": 22.9,
            "features": [
              {
                "name": "Beilage",
                "groupName": "Beilage",
                "minValuesRequired": 1,
                "maxValuesAllowed": 1,
                "valuesForFree": 1,
                "values": [
                  { "name": "Erdäpfelsalat", "priceAdjustment": 0 },
                  { "name": "Pommes frites",  "priceAdjustment": 0 },
                  { "name": "Reis",           "priceAdjustment": 0 }
                ]
              },
              {
                "name": "Ohne",
                "isDeselectFeature": true,
                "values": [
                  { "name": "Preiselbeeren", "priceAdjustment": 0 }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
]

Vollständiges, ungekürztes Beispiel herunterladen: menu-response.json

1. Menu

Oberste Gruppierung im Menübaum; enthält Kategorien. Beispiele: Speisen, Getränke, Angebote.

Mutationen (Auth erforderlich):

2. Category

Unterpunkt eines Menüs. Beispiele: Alkoholfreie Getränke, Bier, Hauptspeisen, Nachspeisen.

Mutationen (Auth erforderlich):

3. MenuEntry

Konkret verkaufbarer Artikel. Beispiele: Wiener Schnitzel, Kaiser Bier.

Mutationen (Auth erforderlich):

4. MenuEntryFeature

Beilagen-/Modifier-Gruppe eines MenuEntry. Beispiele: Gebindegröße, Beilage zur Hauptspeise.

Mutationen (Auth erforderlich):

5. MenuEntryFeatureValue

Einzelne Ausprägung einer Beilage. Beispiele: Bier 0,3 l, Bier 0,5 l, Pommes, Kartoffeln.

Mutationen (Auth erforderlich):

6. Hours

Gültigkeitsfenster an Menüs oder Kategorien. Sie steuern, wann bestellt, vorbestellt oder geliefert werden darf.

Wochentags-Bitmaske:

Beispiel: Mo–Fr ergibt 2 + 4 + 8 + 16 + 32 = 62.

Badges

Optische Hervorhebungen für Menüs, Kategorien und Einträge:

Die Hotel-API ist die bidirektionale Brücke zwischen einer APRO-Kassa und einem Property-Management-System (PMS). Das PMS spielt Reservierungen in die Kassa ein, damit Gäste aufs Zimmer anschreiben können; die Kassa liefert die Zimmerumsätze an das PMS zurück, damit sie auf der Hotelrechnung landen.

• Host: cloudgateway.apro.at (Pfadpräfix /hotelservice/)
• Auth: API-Key im x-api-key
• Content type: application/json
• Ergänzende Referenz: api-docs.apro.at → hotelservice ↗

Typischer Ablauf

PMS                                       APRO POS
 │ 1. POST  /pms/reservations  ─────────▶ │   (Reservierungen upsert)
 │                                        │
 │                                        │  Gäste schreiben aufs Zimmer …
 │                                        │
 │ 2. GET   /pms/charges?hotelId=…  ─────▶│
 │ ◀─── Charges (optional inkl. Receipts) │
 │                                        │
 │ 3. POST  /pms/confirm-charges  ───────▶│   (ack; keine Wiederholung)
 │                                        │
 │ 4. DELETE /pms/reservations?…  ───────▶│   (bei Check-out / Abschluss)

Schritt 2 ist die Polling-Schleife des PMS. Schritte 1 und 4 werden durch Ereignisse im PMS ausgelöst. Schritt 3 muss jeder erfolgreichen Abfrage folgen — sonst werden dieselben Charges beim nächsten Poll wieder geliefert.

1. Reservierungen upserten

Den kompletten aktiven Reservierungsstand ins POS übergeben. Schlüssel sind hotelId + Id + guestId; bestehende Zeilen werden in-place aktualisiert.

POST https://cloudgateway.apro.at/hotelservice/api/v1/pms/reservations

Request-Body

Reservation

Identifier

Beispielanfrage

POST /hotelservice/api/v1/pms/reservations

{
  "reservations": [
    {
      "Id": "Aabc123",
      "hotelId": "1",
      "guestId": "Abc123",
      "roomNr": "Abc123",
      "title": "Mr.",
      "firstName": "Max",
      "lastName": "Mustermann",
      "arrival": "2026-04-02T14:00:00",
      "departure": "2026-04-04T14:00:00",
      "nrOfIndividuals": 1,
      "identifiers": [{ "value": "keycard-uid" }]
    }
  ]
}

Download: hotel-reservations-upsert.json

Beispielantwort

200 OK

{
  "newReservationsCount": 0,
  "checkedOutReservationsCount": 0,
  "updatedReservationsCount": 1,
  "state": 1,
  "isSuccessfull": true,
  "errorCode": 0,
  "message": null,
  "context": null
}

Download: hotel-reservations-response.json

Tipp
Immer den vollständigen aktiven Stand übertragen, keine Deltas.
checkedOutReservationsCount zeigt an, wie viele bisher bekannte
Reservierungen nicht mehr in der Payload waren — diese werden
automatisch ausgecheckt.

2. Charges abfragen

Holt alle seit dem letzten bestätigten Poll auf Zimmer gebuchten Umsätze.

GET https://cloudgateway.apro.at/hotelservice/api/v1/pms/charges
    ?hotelId=1
    &excludeAlreadyExported=true

Query-Parameter

Antwortstruktur

Jedes Element hat ein chargeType, das bestimmt welche Felder befüllt sind:

Top-Level:

Item

LineItem

Beispielantwort

200 OK · Charge + zwei Receipts (gekürzt)

{
  "page": { "limit": 3, "offset": 0, "total": 8096 },
  "data": [
    {
      "chargeType": "Charge",
      "bookDate": "2026-04-15T09:15:04.95",
      "receiptNr": 90,
      "userId": 20,
      "userName": "Johannes",
      "outlet": 1,
      "tableNr": 2,
      "table": "Bar 2",
      "totalAmount": 9.00,
      "tip": 0.30,
      "businesscaseId": "253c225f-7c4a-4d3f-80cd-63de4dbfca9e",
      "reservationId": "   15631",
      "guestId": "    6158",
      "roomNumber": "   414",
      "charges": [
        { "articleNr": 129,  "articleName": "Zipfer 0,2",     "productgroupName": "Bier",        "quantity": 1.00, "unitPrice": 1.10, "vatPercent": 20.00 },
        { "articleNr": 213,  "articleName": "Apfel ltg 0,5",  "productgroupName": "Flaschen AF", "quantity": 1.00, "unitPrice": 2.70, "vatPercent": 20.00 },
        { "articleNr": 1626, "articleName": "Würstel Pommes", "productgroupName": "Hauptspeise", "quantity": 1.00, "unitPrice": 4.90, "vatPercent": 10.00 }
      ]
    }
  ]
}

Vollständiges Beispiel (Charge + zwei Receipts) herunterladen: hotel-charges-response.json

Achtung
String-Felder wie reservationId, guestId oder roomNumber können
links mit Leerzeichen aufgefüllt sein, wenn die Kassa diese Felder
fixer Breite speichert (" 15631"). Im PMS vor dem Matching
trim()en.

3. Charges bestätigen

Bestätigt die erfolgreich verarbeitete Liste. Nach der Bestätigung liefert /charges mit excludeAlreadyExported=true diese businesscaseIds nicht mehr.

POST https://cloudgateway.apro.at/hotelservice/api/v1/pms/confirm-charges

Request-Body

POST /hotelservice/api/v1/pms/confirm-charges

{
  "hotelId": "1",
  "transactionIds": [
    "69F94B1A-3453-7017-8DDB-94E2175D0365",
    "155FFA87-DC19-EB1F-3DD8-540EF62A115D"
  ]
}

Download: hotel-confirm-charges.json

4. Reservierung entfernen

Explizite Entfernung — sinnvoll beim Check-out oder wenn der Gast nicht mehr aufs Zimmer buchen darf.

DELETE https://cloudgateway.apro.at/hotelservice/api/v1/pms/reservations
    ?hotelId=1
    &reservationId=Abc123
    &guestId=Abc123

Alle drei Query-Parameter sind Pflicht. Die betroffene Reservierung wird entfernt, oder der Call ist ein No-Op, falls sie nicht existiert.

Hinweis
In der Praxis reicht der Voll-Upsert aus Schritt 1 — jede Reservierung,
die nicht mehr in der Payload steht, wird automatisch ausgecheckt
(checkedOutReservationsCount). Diesen Endpunkt nur für gezielte
Out-of-Band-Entfernungen nutzen.

Idempotenz & Retries

• POST /pms/reservations ist idempotent über { hotelId, Id, guestId }. Gleicher Payload → gleicher Zustand.
• POST /pms/confirm-charges ist idempotent über transactionIds. Eine erneute Bestätigung derselben ID ist ein No-Op.
• Poll → Confirm muss in eurem System transaktional sein: zuerst die Charges ins Journal schreiben, dann bestätigen. Schlägt die Bestätigung fehl, liefert der nächste Poll dieselben Zeilen erneut.

Fehler

Siehe Authentifizierung → Fehlerantworten. Bei fachlichen Fehlern liefert die Antwort:

{
  "isSuccessfull": false,
  "errorCode": 42,
  "message": "No reservation found for guestId 'Abc123'.",
  "context": { "guestId": "Abc123" }
}

Die Gutschein-API ist die programmatische Schnittstelle zum zentralen APRO-Gutscheinbestand — dieselbe Basis, die Verkaufskarten im Lokal, Online-Gutscheinshops und Treueguthaben speist. Salden sind serverseitig autoritativ; jede Operation liefert den aktualisierten Gutschein zurück, sodass der Aufrufer keinen Zustand lokal tracken muss.

• Host: cloudgateway.apro.at (Pfadpräfix /voucherservice/)
• Auth: API-Key im x-api-key
• Content type: application/json
• Ergänzende Referenz: api-docs.apro.at → voucherservice ↗

Beträge

Alle Geldbeträge sind Integer in Minor-Units (Cent) — 5000 entspricht € 50,00. balance ist das aktuell verfügbare Guthaben; amount ist der ursprüngliche Nennwert; maxAmount (optional) begrenzt das Aufladelimit.

Voucher-Objekt

Das Voucher-Objekt taucht in jeder Antwort auf. Felder:

1. Gutscheine auflisten

GET https://cloudgateway.apro.at/voucherservice/api/v1/vouchers

Liefert alle für den API-Key sichtbaren Gutscheine. Für einzelne Codes den validity-Endpoint nutzen — der ist dafür indiziert.

2. Gültigkeit prüfen

GET https://cloudgateway.apro.at/voucherservice/api/v1/vouchers/validity
    ?voucherCode=560620085

Query-Parameter

Beispielantwort

200 OK

{
  "voucher": {
    "gift": { "amount": 5000, "balance": 3880, "maxAmount": null },
    "id": "f5f4d577-3764-4c25-12f8-08db73dad741",
    "voucherCode": "560620085",
    "codeId": null,
    "startDate": null,
    "expirationDate": null,
    "enabled": true,
    "comment": null,
    "categoryId": 4,
    "categoryName": "OnlineGutschein",
    "categoryNrOfTimesRedeemablePerUnit": null,
    "categoryExternalPaymentProviderId": null,
    "createdAt": "2023-06-23T11:13:15.6386753",
    "discriminator": "GiftVoucherDto"
  },
  "errors": [],
  "isValid": true
}

Download: voucher-validity-response.json

isValid: false + befüllter errors-Array sagt, warum der Gutschein gerade nicht einlösbar ist. Häufige Codes:

3. Gutschein ausstellen

POST https://cloudgateway.apro.at/voucherservice/api/v1/vouchers/gifts

Legt einen neuen Gutschein an. Bei Erfolg ist der HTTP-Status 201 Created und der Location-Header verweist auf die neue Ressource.

Request-Body

Beispielanfrage

POST /voucherservice/api/v1/vouchers/gifts

{
  "categoryId": 1,
  "voucherCode": "2131231",
  "comment": "Ersatzkarte — Original verloren",
  "gift": { "amount": 50, "maxAmount": 10000 },
  "clientType": "<von-apro-vergeben>",
  "clientContext": "{\"outletId\":\"231231\"}",
  "startDate": "2026-01-01T00:00:00",
  "expirationDate": "2028-12-31T23:59:59"
}

Download: voucher-issue-request.json

Beispielantwort

201 Created

{
  "data": {
    "gift": { "amount": 50, "balance": 50, "maxAmount": 10000 },
    "id": "e961c17d-d037-4d27-734d-08ddda944e39",
    "voucherCode": "2131231",
    "categoryId": 1,
    "categoryName": "Standard",
    "enabled": true,
    "comment": "Ersatzkarte — Original verloren",
    "startDate": "2026-01-01T00:00:00",
    "expirationDate": "2028-12-31T23:59:59",
    "createdAt": "2026-04-20T21:33:00.000+02:00",
    "discriminator": "GiftVoucherDto"
  }
}

Download: voucher-issue-response.json

4. Gutschein einlösen

POST https://cloudgateway.apro.at/voucherservice/api/v1/vouchers/{voucherId}/redemption

Zieht amount Minor Units vom Guthaben ab. Der Pfadparameter ist die interne id (nicht der voucherCode) — zu erhalten über /validity.

Request-Body

Beispielanfrage

POST /voucherservice/api/v1/vouchers/{id}/redemption

{
  "redemption": { "amount": 50 },
  "clientReference": "{ \"waiterId\": 10 }",
  "clientContext": "{\"outletId\":\"231231\"}",
  "comment": "Eingelöst an Bar 2 zu Beleg 5906",
  "clientType": "<von-apro-vergeben>"
}

Download: voucher-redeem-request.json

Beispielantwort

200 OK

{
  "data": {
    "redemption": { "amount": 50, "items": [] },
    "success": true,
    "errors": [],
    "transactionId": 21142,
    "voucher": {
      "gift": { "amount": 5000, "balance": 3830, "maxAmount": null },
      "id": "f5f4d577-3764-4c25-12f8-08db73dad741",
      "voucherCode": "560620085",
      "categoryId": 4,
      "categoryName": "OnlineGutschein",
      "enabled": true,
      "discriminator": "GiftVoucherDto"
    }
  }
}

Download: voucher-redeem-response.json

Die transactionId (integer) ist die autoritative ID der Einlösung — für Abgleich und Refunds persistieren.

5. Gutschein aufbuchen

POST https://cloudgateway.apro.at/voucherservice/api/v1/vouchers/{voucherId}/booking

Bucht amount Minor Units zurück auf den Gutschein — etwa beim Aufladen einer Mehrweg-Karte oder bei Rückbuchungen.

Request-Body

Beispielanfrage

POST /voucherservice/api/v1/vouchers/{id}/booking

{
  "amount": 1000,
  "clientReference": "{ \"waiterId\": 10 }",
  "clientType": "<von-apro-vergeben>",
  "clientContext": "{\"outletId\":\"231231\"}",
  "comment": "Aufladung nach Guthabenzukauf"
}

Download: voucher-booking-request.json

Beispielantwort

200 OK

{
  "data": {
    "newAmount": 4830,
    "success": true,
    "errors": [],
    "transactionId": 21143,
    "voucher": {
      "gift": { "amount": 5000, "balance": 4830, "maxAmount": null },
      "id": "f5f4d577-3764-4c25-12f8-08db73dad741",
      "voucherCode": "560620085",
      "categoryName": "OnlineGutschein",
      "enabled": true,
      "discriminator": "GiftVoucherDto"
    }
  }
}

Download: voucher-booking-response.json

clientType

clientType identifiziert das aufrufende System, damit der Gutschein-Ledger weiß, welche Integration eine Transaktion erzeugt hat. APRO vergibt für jede Integration beim Onboarding einen eigenen clientType-Wert — der konkrete String ist nicht frei wählbar und wird zusammen mit dem API-Key übermittelt. Immer den von APRO bereitgestellten Wert verwenden, nie selbst erraten.

Fehlerbehandlung

• HTTP 4xx bei Validierungsfehlern (ungültige voucherId, malformed Body, fehlende Auth). Siehe Authentifizierung → Fehlerantworten.
• HTTP 200 mit success: false bei fachlichen Regeln (zu wenig Guthaben, abgelaufen …). errors-Array inspizieren.
• Niemals clientseitig retryen ohne vorherige Validierung. Timeout auf einen Einlösen-Call? Zuerst /validity aufrufen — die Operation kann serverseitig bereits angewendet sein.

Das Gutschein-Widget ist eine <giftcard-widget>-Webkomponente, die den APRO-Gutscheinshop für eine Location in einem iframe lädt. Zwei Zeilen genügen — Kundinnen und Kunden kaufen und personalisieren Gutscheine, ohne die Host-Seite zu verlassen.

• Skript: https://smorderfrontend.azureedge.net/embed/widget.js
• Tag: <giftcard-widget location-id="…">
• Drei Modi: Inline-Liste (Gutscheinliste füllt den Container), Inline-Button (Button im Seitenfluss öffnet ein Panel) oder schwebender Button (fixierter FAB öffnet ein Panel)

Schnellstart

Minimale Einbindung — Skript einmal laden, danach das Tag dort einsetzen, wo der Shop erscheinen soll:

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>
<giftcard-widget location-id="535"></giftcard-widget>

Mehr braucht es nicht. Das Widget lädt die Gutscheinkategorien der Location, rendert den Shop und führt durch den gesamten Kaufvorgang. Die Host-Seite muss lediglich Platz für das Layout bereitstellen.

Beispiel — Inline-Button

Gerendert mit presentation="inline-button". Der Trigger steht im Seitenfluss genau dort, wo das <giftcard-widget>-Tag platziert ist; ein Klick öffnet den Gutscheinshop in einem Modal-Panel.

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>
<giftcard-widget
  location-id="535"
  locale="de"
  presentation="inline-button"
  expand-icon="redeem"
  expand-label="Gutscheine"
  headline="Gutschein kaufen"
  max-height="700"
></giftcard-widget>

<div style="padding:1rem; margin:1.25rem 0;">
<giftcard-widget location-id="535" locale="de" presentation="inline-button" expand-icon="redeem" expand-label="Gutscheine" headline="Gutschein kaufen" max-height="700" ></giftcard-widget>
</div>

Beispiel — Inline-Liste

Dasselbe Widget ohne presentation — die volle Gutscheinliste fügt sich in den Seitenfluss ein, begrenzt durch max-height.

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>
<giftcard-widget
  location-id="535"
  locale="de"
  max-height="700"
></giftcard-widget>

<style>{giftcard-widget:not([presentation]) { display: block; min-height: 320px; }}</style>

<div style="border:1px dashed var(--sl-color-gray-5); border-radius:10px; padding:1rem; margin:1.25rem 0; min-height:740px;">
<giftcard-widget location-id="535" locale="de" max-height="700" style="display:block; height:700px;" ></giftcard-widget>
</div>

Interaktiver Builder

Attribute unten anpassen — Markup und Vorschau aktualisieren sich sofort. Den fertigen Schnipsel direkt ins CMS oder Template kopieren.

Inline-Button-Modus

Empfohlener Standard. Mit presentation="inline-button" wird der Trigger genau dort gerendert, wo das <giftcard-widget>-Tag platziert ist. Ein Klick öffnet den Gutscheinshop in einem Modal-Panel. Das Layout der Host-Seite bleibt unverändert, bis der Kunde aktiv wird.

<giftcard-widget
  location-id="535"
  locale="de"
  presentation="inline-button"
  expand-icon="redeem"
  expand-label="Gutscheine"
  headline="Gutschein kaufen"
  max-height="700"
></giftcard-widget>

Schwebender-Button-Modus

Mit presentation="expandable" wechselt das Widget in den fixierten FAB-Modus: ein runder Pill-Button in einer von sechs Ecken öffnet ein verankertes Panel mit dem Shop. Praktisch, wenn dauerhaft ein Einstiegspunkt sichtbar sein soll, der dem Besucher beim Scrollen folgt.

<giftcard-widget
  location-id="535"
  locale="de"
  presentation="expandable"
  position="right-bottom"
  max-height="700"
  max-width="420"
  expand-label="Gutscheine"
  expand-icon="card_giftcard"
  headline="Gutschein kaufen"
></giftcard-widget>

position steuert sowohl die FAB-Position als auch die Kante, an der das Panel andockt. Erlaubte Werte:

• right-bottom (Standard), left-bottom, center-bottom
• right-top, left-top, center-top

expand-icon ist ein Material-Icons-Ligaturname (z. B. redeem, card_giftcard, celebration). Wird über @fontsource/material-icons im Embed gebündelt — Bild-URLs werden nicht unterstützt.

expand-theme schaltet zwischen dark (Standard) und light für die Optik. Die Modal-Titelleiste folgt demselben Theme — dunkel im Standard, hell bei expand-theme="light".

Inline-Listen-Modus

presentation weglassen (oder leer setzen), um die volle Gutschein­liste in den Seitenfluss zu rendern. Das Widget übernimmt die Breite des Elternelements und wächst bis zur natürlichen iframe-Höhe, begrenzt durch max-height. Geeignet für eine dedizierte „Gutscheine"-Landingseite.

<giftcard-widget
  location-id="535"
  locale="de"
  max-height="700"
></giftcard-widget>

Attribute

Skript einbinden

widget.js einmal pro Seite laden — beliebig im <head> oder vor </body>. Das Skript registriert das <giftcard-widget>-Custom-Element global; nachfolgende Tags aktivieren sich automatisch.

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>

Mehrere Widgets auf einer Seite sind unterstützt (z. B. ein Inline-Shop plus ein ausklappbares FAB an anderer Stelle). Jedes iframe ist isoliert.

Wenn direkter SQL-Zugriff auf die Kassa gefragt ist — meist weil APRO On-Premise neben bestehenden Systemen läuft — stellt die Kassendatenbank einen stabilen Satz lesender Views bereit. Sie sind gezielt auf die beiden häufigsten Konsumenten zugeschnitten:

• On-Premise-Integrationen — Buchhaltungsbrücken, Küchenmonitore, Warenwirtschaft, Loyalty-Engines — alles, was im selben Netz läuft und einen schnellen Datenfluss ohne Umweg über REST braucht.
• Bestehende BI-Workflows — Power BI, Tableau, Qlik, Metabase, Excel, SQL Server Analysis Services — jedes Tool, das bereits SQL-Server-Connections versteht. Connector auf die Views zeigen und du hast Belege, Positionen, Zahlungen und Artikelstamm in der Form, die ein Data Warehouse erwartet.

Die Views sind ausschließlich lesend, über das Standard-SQL-Server- Protokoll abfragbar und greifen nicht auf operative Tabellen zu, die unter Last mutieren — sie sind sicher für Dashboards und geplante ETL-Jobs.

Tipp: SQL Views oder Umsatz API?
Die SQL-Views und die Umsatz API liefern dieselben
Daten — wähle die passende Laufzeit:

- SQL Views (diese Seite) — flach, relational, On-Premise.
Perfekt für ETL, Power-BI-/Tableau-/Qlik-/Metabase-Konnektoren und
jeden Workflow, der SQL-Bulk-Zugriff will.
- Umsatz API — über den Cloud-Endpunkt my.apro.at, liefert ein
hierarchisches JSON-Dokument mit Positionen, Zahlungen und
Steuersätzen bereits pro Beleg verschachtelt. Besser für Realtime-
System-zu-System-Integrationen, SaaS-Clients und alles ausserhalb
des lokalen Netzes.

Hinweis
Der lesende SQL-User wird pro Deployment bereitgestellt. Freischaltung,
Servername, Datenbank und Zugangsdaten bekommst du über deine
APRO-Ansprechperson.

Übersicht

1. vw_Receipts

Eine Zeile pro Geschäftsvorfall. Die Spalte TransactionType sagt, was die Zeile repräsentiert; Beträge sind vorzeichenbehaftet — bei Stornos (TransactionType = 4) sind sie negiert, damit SUM(TotalAmount) direkt netto rechnet.

Transaktionstypen

Die View enthält nur Transaktionen mit TransactionType in (1, 2, 3, 4, 5, 14, 24, 25). Das autoritative Mapping liegt in vw_TransactionTypes und ist auch pro Zeile als TransactionTypeName beigefügt.

2. vw_Receipt_Items

Positionen. Join mit vw_Receipts über ReceiptId / TransactionId. Werte sind wie beim Beleg vorzeichenbehaftet.

3. vw_Payments

Zahlungen zu Belegen. Enthalten sind nur Abrechnungen und ihre Rückholungen (TransactionType in (3, 4, 5, 14, 24, 25)).

4. vw_Transactions

Leichter Index aller Transaktionen. Nützlich für Wasserzeichen-ETL (nur neue Zeilen seit dem letzten Checkpoint ziehen).

5. vw_TransactionTypes

Lookup aller Transaktionstypen, die die Kassa erzeugt.

6. vw_Bi_Export

Die One-Stop-View für BI-Tools. Denormalisierter Join aller umsatzrelevanten Belege mit all ihren Positionen, plus einer komma-separierten Zusammenfassung der verwendeten Zahlungsmittel. Power BI oder Tableau auf diese View zeigen — und du hast alles für Umsatz-, Marge-, Mix- und Zahlungsmittel-Dashboards, ohne Joins schreiben zu müssen.

Spalten sind die Vereinigung von vw_Receipts und vw_Receipt_Items (ohne TransactionTypeId, das nur auf der Belegseite vorkommt), plus:

Power-BI-Beispiel

1. Daten abrufen → SQL-Server-Datenbank — Server + Datenbank wie bereitgestellt.
2. Import- oder DirectQuery-Modus, lesender User.
3. dbo.vw_Bi_Export als Fakt-Tabelle wählen.
4. Optional dbo.vw_Transactions, dbo.vw_Payments, dbo.vw_products_and_categories als Dimensions-Tabellen hinzufügen und über TransactionId / ProductId verknüpfen.

Der Import-Modus reicht in der Regel — die Views sind bereits auf Transaktionsebene aggregiert und aktualisieren sich bei einem typischen Betrieb in Sekunden.

7. vw_products_and_categories

Artikelstamm mit Sparte. Eignet sich als Dimension neben vw_Bi_Export, wenn BI-Artikelnamen stabil bleiben sollen, auch wenn historische Zeilen vor einer Umbenennung liegen.

Nur Artikel mit Geloescht = 0 (nicht soft-gelöscht) sind enthalten.

Beispiel-Queries

Umsatz pro Geschäftstag, nach Steuersatz — für einen Monats-KPI:

SELECT
  r.BusinessDay,
  ri.TaxName,
  SUM(ri.EffectiveAmount) AS netto_umsatz
FROM vw_Receipts AS r
JOIN vw_Receipt_Items AS ri ON ri.ReceiptId = r.Id
WHERE r.TransactionType IN (3, 4, 5)   -- Abrechnungen + Stornos rechnen netto
  AND r.BusinessDay BETWEEN @from AND @to
GROUP BY r.BusinessDay, ri.TaxName
ORDER BY r.BusinessDay, ri.TaxName;

Top-10-Artikel im aktuellen Monat — direkt über die BI-View:

SELECT TOP 10
  ProductName,
  SUM(Quantity)        AS stueck,
  SUM(EffectiveAmount) AS netto_umsatz
FROM vw_Bi_Export
WHERE BusinessDay >= DATEFROMPARTS(YEAR(GETDATE()), MONTH(GETDATE()), 1)
  AND TransactionType IN (3, 4, 5)
GROUP BY ProductName
ORDER BY netto_umsatz DESC;

Bar vs. Karte für einen einzelnen Geschäftstag:

SELECT
  PaymentTypeName,
  SUM(TotalAmount) AS total
FROM vw_Payments
WHERE CAST(DateTime AS date) = @businessDay
GROUP BY PaymentTypeName;