APIs

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.