External Catalog API

The External Catalog API exposes a slim, read-only view of the master data inside an APRO location — the products, product categories and spots (tables, rooms, pickup points) — for use in white-label apps, kiosks, external menus and partner integrations.

The three endpoints share the same conventions: scoping by location, nested DTO shape, filtering via query parameters, and pagination.

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

Tip: Try it in Postman
Download the ready-to-run collection:
apro-external-catalog.postman_collection.json.
Import it into Postman, set apiKey and locationShortCode in the
collection's Variables tab, hit Send.

Caution: Filters use a bracketed query syntax
All filter fields — including the required locationId /
locationShortCode — must be passed as filter['<name>']=<value>,
not as plain query parameters. Plain ?locationShortCode=… is
silently ignored and the request fails with "location not resolved".
See Filtering for full rules.

Endpoints

Common conventions

Scoping to a location

Every request must address one concrete location. Provide one of:

1. locationId — numeric ID
2. locationShortCode — short string identifier (e.g. vienna-main)

If neither resolves to an existing location, the request is rejected with 400 Bad Request.

Pagination

Every response is wrapped in a paged envelope:

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

• offset and limit echo the request.
• total is the total number of records matching the filter, across all pages — use it to drive skip/take loops.

Filtering

Filters are passed as bracketed query parameters under the filter key — filter['<name>']=<value>. Plain ?<name>=<value> is ignored. Pagination (skip, take) stays as plain query params.

List-valued filters (productIds, gtins, externalSpotIds, …) are comma-separated. Escape literal commas with \,.

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

Notes:

• The bracket key is case-insensitive — filter['LocationShortCode'] and filter['locationShortCode'] are equivalent.
• filter["…"] (double quotes, URL-encoded as %22) works too.
• Unknown filter parameters are ignored.

Products

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

Query parameters

Product

Pricing

ProductCashbox

Media

Flags

Nutrition

Ingredient

NutritionalValue

Localization

The top-level name, subtitle, description and media.imageUrl always carry the default (German) values — localizations never replaces them, it only adds the translations that exist. Entries without a locale key are omitted, and individual fields inside an entry may be null when that particular text was not translated. Resolve a display string by looking for the caller's locale in localizations and falling back to the top-level field.

Example

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
        }
      ]
    },
    {
      "id": 9002,
      "productNr": "A-110",
      "gtin": null,
      "externalProductId": null,
      "name": "Tafelspitz",
      "externalName": null,
      "subtitle": null,
      "description": null,
      "pricing": { "defaultPrice": 24.5, "referencePrice": null, "taxRateId": 3, "allowClientPrice": false },
      "cashbox": { "cashboxId": 17, "productionPlaceId": 2, "parentProductId": null },
      "media": { "imageUrl": null },
      "flags": { "isVisible": true, "isLocked": false, "queuedForReview": false },
      "nutrition": { "amount": null, "amountUnit": null, "calories": null, "allergens": 0, "minimumAge": 0, "ingredients": [], "nutritionalValues": [] },
      "productGroupExternalIds": ["mains"],
      "localizations": []
    }
  ]
}

Download: external-products-response.json

Product categories

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

Categories correspond to APRO product groups — the cashbox-scoped grouping that drives reports, tax rates and printing order. The productGroupExternalIds field on a product references the same externalId returned here, so you can join the two responses without extra lookups.

Query parameters

ProductCategory

CategoryCashbox

CategoryTax

CategoryLocalization

Same rules as on products: the top-level name stays the default (German) value and localizations only adds what exists.

Example

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 are the physical / logical destinations a guest can order to: tables, rooms, pickup counters, delivery zones, drive-in lanes.

Query parameters

Spot

SpotLocation

SpotArea

SpotGeo

SpotFlags

Example

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
      }
    },
    {
      "id": 1502,
      "externalSpotId": "table-02",
      "number": 2,
      "name": "Tisch 2",
      "alternativeName": null,
      "description": null,
      "qrCode": "QR-02",
      "type": "Table",
      "capacity": 2,
      "location": { "locationId": 7236, "locationShortCode": "vienna-main" },
      "area": { "areaId": 11, "name": "Gastgarten", "externalAreaId": "garden" },
      "geo": { "latitude": 48.2082, "longitude": 16.3738 },
      "flags": {
        "visibleInApp": true,
        "supportsTableOrder": true,
        "supportsCashPayment": true,
        "defaultToTakeAway": false,
        "displayAsButton": false
      }
    }
  ]
}

Download: external-spots-response.json

Cross-API joins

These three endpoints are designed to be joined client-side:

• product.productNr ↔ productNr (entry / addon) on the External Order API — case-insensitive, matched only against products on the location's primary cashbox. When productNr doesn't resolve, the order pipeline falls back to matching the entry's name against product.name.
• product.productGroupExternalIds[i] ↔ productCategory.externalId
• product.cashbox.cashboxId / productCategory.cashbox.cashboxId ↔ cashboxId filter on either endpoint
• spot.location.locationShortCode ↔ locationShortCode filter everywhere
• spot.id ↔ SpotID on the External Order API — pass the spot's id straight back to route an order to the same spot it was read from. spot.qrCode maps to the External Order API's QRCode field.

Errors