Externer Katalog API

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