Developer Documentation

APRO is the modular point-of-sale platform for restaurants, hotels, food trucks and system gastronomy — built to connect. Hotel software, accounting, payments, delivery services, reservation systems, access control, digital signage: APRO plugs into your existing stack for end-to-end processes and maximum automation.

This site is the developer documentation for teams building on that surface: partners wiring up reservation or inventory systems, delivery marketplaces routing orders into the POS, BI tools reading the ledger, or in-house teams automating reports.

What you will find here

• REST APIs. Stable, JSON-over-HTTPS endpoints for the domains below. Every endpoint is authenticated with a single API key — no SDK required, no OAuth dance to orchestrate.
• SQL views. Read-only views for direct database access, useful for BI pipelines and data warehouses.
• Payload samples. Every example on this site is backed by a standalone JSON file under /samples/ that you can download and replay.
• Full API reference. The machine-readable contract is published at api-docs.apro.at.

Pick your starting point

Status and versioning

Endpoints under /api/v1/… are considered stable. Breaking changes are announced in the release notes on apro.at. New optional fields and non-breaking response additions can land at any time — parsers should tolerate unknown keys.

Support

• Commercial & onboarding: apro.at/support
• Integration questions: reach out through your APRO account manager.

All APRO REST endpoints use a single API key, passed in the x-api-key request header. There is no OAuth flow and no token refresh — keys are long-lived and scoped to either a tenant or a single location.

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

Every APRO REST key is scoped to a single location. A request succeeds only if the location derived from the endpoint matches the location bound to the key.

A location-scoped key fails closed if reused against another location and is safe to hand to a partner or a single deployment.

Obtaining a key

Keys are issued by the APRO account team. Contact your account manager or apro.at/support to request one. Rotation is supported; the retired key is kept valid for a grace period so you can roll over without downtime.

Storing keys

• Never commit a key to source control.
• Store keys in a secret manager (Azure Key Vault, 1Password, HashiCorp Vault, GitHub Actions / Azure DevOps secrets).
• Inject them at runtime as environment variables (APRO_API_KEY).

Error responses

The Revenue API returns every fiscal transaction in a date range — with its positions, payments and tax breakdown — in a single call. Use it for accounting exports, revenue reconciliation, BI warehouses or ad-hoc reports.

Tip: Revenue API or SQL Views?
The Revenue API and the SQL Views expose the
same underlying data, but in different shapes for different runtimes:

- Revenue API — served over the public cloud endpoint
(my.apro.at). Returns a hierarchical JSON document per receipt
with positions, payments, tax, staff and table already nested. Ideal
for off-premise systems, SaaS integrations, mobile clients and any
consumer that wants a ready-to-use object tree.
- SQL Views — read-only views on the on-premise cash register
database. Flat, relational, queryable with any tool that speaks
SQL Server. Ideal for on-premise integrations, ETL pipelines and
existing BI workflows (Power BI, Tableau, Qlik, Metabase).

Pick the cloud API for real-time system-to-system integration, pick
the SQL views for bulk analytics and dashboards.

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

Endpoints

Both variants require a location-scoped API key. The key itself determines which location's data is returned — there is no tenant-wide variant. Pick whichever feels more explicit in your client code — both return the same data and require the same key.

Request body

Example request

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

Response

An array of receipts. Each element is one transaction with its positions, payments and metadata.

Top-level fields

Item

Side dish

Side dishes (Unterartikel) are the modifiers booked underneath a line item — the Pommes under a schnitzel, the ohne Zwiebel on a burger. They are returned nested inside their parent item, never as items of their own.

A side dish reuses the Item shape, but only the following fields are populated. Every other field — bookDate, externalId, purchasePrice, course, tax, category, sideDishes — is null or its zero value, and side dishes do not nest recursively.

Caution: Do not add side dishes to your totals
A side dish that carries a surcharge is **already included in its
parent item's grossAmount / netAmount** and in the receipt's
totalAmount. Summing sideDishes[].grossAmount on top of the parent
line double-counts revenue. Treat the amounts as a breakdown for
display, not as separate positions.

sideDishes is null — not [] — when a line has none, and also on older query configurations that predate the feature. Test for null-or-empty rather than assuming an array is present.

Tax

Category

Payment

Payment type

Business

Staff

Table

Location

Area

The room or zone a table sits in.

Payment group

The grouping payment types roll up into — used for cash-book and settlement reporting.

Customer

Note: Always null today
The receipts endpoint never populates customer — it is reserved in the
response contract but not filled by the query. Do not build invoice-
recipient logic on it; resolve customers through their own endpoints
instead.

Example response

Response · two receipts settled back-to-back

[
  {
    "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
  }
]

Download the same payload as a standalone file: revenue-response.json

Transaction types

The transactionType discriminates what the row represents. For revenue-effective reports, filter on Abrechnen (and RechnungZurückholen for reversals).

Calculating revenue

To compute revenue-effective turnover over a response, keep only paid settlements and their reversals, and sum the net line totals:

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

There is no cursor-in-response — use the deterministic transactionId of the last row you saw as afterTransactionID on the next request, keeping after/before unchanged. Continue until the response contains fewer rows than your limit.

Errors

See Authentication → Error responses.

The External Order API accepts a fully-formed order from any external system — a delivery aggregator, a white-label app, a kiosk, a voice agent — and routes it into the running APRO POS at the target location. A single POST is enough; the order appears on the order-manager screen immediately.

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

Routing the order to a location

The order must be addressable to one concrete location. Provide one of the following — the first that is non-null wins:

1. LocationID — numeric ID
2. LocationShortCode — short string identifier (e.g. vienna-main)
3. SpotID — a specific table/room/pickup spot (location is derived)
4. QRCode — a scanned APRO QR code (location and spot are derived)

If none is provided, the request is rejected.

Request body

Entry

Addon

UserInfo

DeliveryInfo

Examples

Minimal order

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

Full order with delivery and add-ons

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

Idempotency

Always set guid to a stable, client-generated UUID. APRO uses it to deduplicate retries — if a response is lost in transit and you retry, the second POST is a no-op and returns success.

Pricing

APRO re-prices every line server-side from productNr. price on an entry or add-on only takes effect when explicitly passed; grandTotal is checked against the server total and an inconsistent payload is rejected. Use it both as a safety net and as a mechanism to pass through campaign-specific discounts.

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

The Online Menu API serves the public menu structure for white-label apps, self-order kiosks and QR-ordering flows. Reading is unauthenticated; every mutating call requires authentication.

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

Fetching a menu

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

• Auth: none
• Example: my.apro.at/api/v1/locations/7236/menus

The response is a tree. Levels, from outermost to innermost:

1. Menu — top-level grouping (e.g. Food, Drinks, Deals).
2. Category — section inside a menu (e.g. Mains).
3. MenuEntry — a concrete sellable item.
4. MenuEntryFeature — add-on / modifier group on an item.
5. MenuEntryFeatureValue — one option inside a feature.
6. Hours — availability windows that can attach to menus and categories.

Example response (abridged)

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 }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
]

Download the full, unabridged sample: menu-response.json

1. Menu

Outermost grouping in the menu tree; contains categories. Examples: Food, Drinks, Deals.

Mutations (auth required):

2. Category

Sub-section of a menu. Examples: Non-alcoholic drinks, Beer, Mains, Desserts.

Mutations (auth required):

3. MenuEntry

A concrete sellable item. Examples: Wiener Schnitzel, Kaiser Bier.

Mutations (auth required):

4. MenuEntryFeature

A modifier group for a menu entry. Examples: Size, Side for main.

Mutations (auth required):

5. MenuEntryFeatureValue

One concrete option inside a feature. Examples: Beer 0.3 l, Beer 0.5 l, Fries, Potatoes.

Mutations (auth required):

6. Hours

Availability windows attached to menus or categories. They gate ordering, pre-ordering and delivery.

Weekday bitmask:

Example: Mon–Fri is 2 + 4 + 8 + 16 + 32 = 62.

Badges

Visual flags for menus, categories and entries. Values:

The Hotel API is a two-way bridge between an APRO point-of-sale and any Property Management System (PMS). The PMS pushes reservations into the POS so that guests can charge to their room; the POS exposes those charges back to the PMS so they land on the final hotel invoice.

• Host: cloudgateway.apro.at (path prefix /hotelservice/)
• Auth: API key in x-api-key
• Content type: application/json
• Upstream reference: api-docs.apro.at → hotelservice ↗

Typical flow

PMS                                       APRO POS
 │ 1. POST  /pms/reservations  ─────────▶ │   (upsert guest rooms)
 │                                        │
 │                                        │  guests charge to room…
 │                                        │
 │ 2. GET   /pms/charges?hotelId=…  ─────▶│
 │ ◀─── charges (and optionally receipts) │
 │                                        │
 │ 3. POST  /pms/confirm-charges  ───────▶│   (ack; won't be resent)
 │                                        │
 │ 4. DELETE /pms/reservations?…  ───────▶│   (on check-out / close-out)

Step 2 is the PMS's polling loop. Steps 1 and 4 are driven by events in the PMS. Step 3 must always follow a successful poll — otherwise the same charges will be returned again on the next poll.

1. Upsert reservations

Push the current list of active reservations into the POS. Keys are hotelId + Id + guestId; existing rows are updated in place.

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

Request body

Reservation

Identifier

Example request

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

Example response

200 OK

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

Download: hotel-reservations-response.json

Tip
Push the full active reservation set on every call, not deltas.
checkedOutReservationsCount reflects reservations the POS was tracking
but which are no longer in your payload — it removes them automatically.

2. Poll charges

Fetch everything booked against rooms since the last confirmed poll.

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

Query parameters

Response shape

Each item has a chargeType that controls which fields are populated:

Top-level envelope:

Item

LineItem

Example response

200 OK · charge + two receipts

{
  "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 }
      ]
    }
  ]
}

Download the full sample (Charge + two Receipts): hotel-charges-response.json

Caution
String fields like reservationId, guestId, roomNumber may be left-
padded with spaces when the POS stores them as fixed-width columns
(" 15631"). Trim on the PMS side before matching.

3. Confirm charges

Acknowledge the list you've successfully ingested. Once confirmed, the POS won't return those businesscaseIds on a subsequent poll with excludeAlreadyExported=true.

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. Remove a reservation

Explicit removal — useful at check-out or when the guest should no longer be able to charge to the room.

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

All three query parameters are required. Either the targeted reservation is removed, or the call is a no-op if it doesn't exist.

Note
In practice the full-set upsert on step 1 is enough — any reservation
no longer present in the payload is checked out automatically
(checkedOutReservationsCount). Use this endpoint only when you need
an explicit out-of-band removal.

Idempotency & retries

• POST /pms/reservations is idempotent on { hotelId, Id, guestId }. Re-sending the same payload converges to the same state.
• POST /pms/confirm-charges is idempotent on transactionIds. Re-confirming an already-confirmed ID is a no-op.
• Poll → confirm must be transactional in your own system: write the charges to your ledger first, then confirm. If the confirm fails, the same rows are returned next poll.

Errors

See Authentication → Error responses. On business-logic failures the response shape is:

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

The Voucher API is the programmatic interface to APRO's central voucher ledger — the same system that powers in-store gift cards, online voucher shops, and loyalty credit. Balances are authoritative server-side; every operation returns the updated voucher so the caller never has to track state locally.

• Host: cloudgateway.apro.at (path prefix /voucherservice/)
• Auth: API key in x-api-key
• Content type: application/json
• Upstream reference: api-docs.apro.at → voucherservice ↗

Amounts

All monetary fields are integer minor units (cents) — 5000 means € 50.00. balance is the currently-available amount; amount is the original face value; maxAmount (optional) caps the ceiling for top-ups.

Voucher shape

The voucher object appears in every response. Fields:

1. List vouchers

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

Returns every voucher visible to the API key. Use the validity endpoint instead when you just need to look up one code — it's indexed for that path.

2. Check validity

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

Query parameters

Example response

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 + a populated errors array indicates why the voucher cannot be redeemed right now (expired, disabled, wrong date window, redemption cap reached). Common error codes:

3. Issue a voucher

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

Creates a new gift voucher. On success the HTTP status is 201 Created and the response Location header points at the new resource.

Request body

Example request

POST /voucherservice/api/v1/vouchers/gifts

{
  "categoryId": 1,
  "voucherCode": "2131231",
  "comment": "Gift card — reprint for a lost original",
  "gift": { "amount": 50, "maxAmount": 10000 },
  "clientType": "<provided-by-apro>",
  "clientContext": "{\"outletId\":\"231231\"}",
  "startDate": "2026-01-01T00:00:00",
  "expirationDate": "2028-12-31T23:59:59"
}

Download: voucher-issue-request.json

Example response

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": "Gift card — reprint for a lost original",
    "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. Redeem a voucher

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

Burns amount minor units off the balance. Path parameter is the voucher's internal id (not the voucherCode) — you get it from /validity.

Request body

Example request

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

{
  "redemption": { "amount": 50 },
  "clientReference": "{ \"waiterId\": 10 }",
  "clientContext": "{\"outletId\":\"231231\"}",
  "comment": "Redeemed at Bar 2 against receipt 5906",
  "clientType": "<provided-by-apro>"
}

Download: voucher-redeem-request.json

Example response

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

The transactionId (integer) is the authoritative ID for this redemption — persist it for reconciliation and refunds.

5. Top up a voucher

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

Adds amount minor units back onto the voucher, e.g. when a customer re-charges a multi-use card or a refund flows back.

Request body

Example request

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

{
  "amount": 1000,
  "clientReference": "{ \"waiterId\": 10 }",
  "clientType": "<provided-by-apro>",
  "clientContext": "{\"outletId\":\"231231\"}",
  "comment": "Top-up after customer added credit"
}

Download: voucher-booking-request.json

Example response

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 identifies the calling system so the voucher ledger knows which integration created a transaction. APRO assigns a clientType value to every integration at onboarding time — the exact string is not self-selectable and is shared with you together with the API key. Always use the value provided by APRO; never hard-code a guess.

Error handling

• HTTP 4xx on validation failures (bad voucherId, malformed body, missing auth). See Authentication → Error responses.
• HTTP 200 with success: false on business rule failures (insufficient balance, expired, etc.). Inspect the errors array.
• Never replay a redemption on the client side. If a response times out, query /validity to confirm the balance before retrying — the operation may already be applied server-side.

The voucher widget is a <giftcard-widget> web component that loads the APRO voucher shop for a single location in an iframe. Drop two lines into any page and customers can browse, buy and personalise gift cards without leaving the host site.

• Script: https://smorderfrontend.azureedge.net/embed/widget.js
• Tag: <giftcard-widget location-id="…">
• Three modes: inline list (the voucher list fills its container), inline button (a button is rendered in the page flow and opens a panel), or floating button (a fixed FAB opens a panel)

Quick start

The minimum embed — load the script once, then add the tag wherever the shop should appear:

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

That's it. The widget queries the location's voucher categories, renders the shop, and handles the customer flow through to checkout. The host page only needs to provide layout space.

Live sample — inline button

Rendered with presentation="inline-button". The trigger sits in the page flow exactly where the <giftcard-widget> tag is placed; clicking it opens the voucher shop in a modal panel.

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>
<giftcard-widget
  location-id="535"
  locale="en"
  presentation="inline-button"
  expand-icon="redeem"
  expand-label="Vouchers"
  headline="Buy a voucher"
  max-height="700"
></giftcard-widget>

<div style="padding:1rem; margin:1.25rem 0;">
<giftcard-widget location-id="535" locale="en" presentation="inline-button" expand-icon="redeem" expand-label="Vouchers" headline="Buy a voucher" max-height="700" ></giftcard-widget>
</div>

Live sample — inline list

Same widget without presentation set — the full voucher list drops into the page flow up to a fixed max-height.

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>
<giftcard-widget
  location-id="535"
  locale="en"
  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="en" max-height="700" style="display:block; height:700px;" ></giftcard-widget>
</div>

Interactive builder

Tweak any attribute below — the markup updates instantly and the preview re-mounts the widget with the new configuration. Copy the final snippet straight into your CMS or template.

Inline-button mode

The recommended default for most pages. Set presentation="inline-button" to render the trigger in the page flow exactly where the <giftcard-widget> tag is placed. Clicking it opens the voucher shop inside a modal panel. The host page's layout stays untouched until the customer opts in.

<giftcard-widget
  location-id="535"
  locale="en"
  presentation="inline-button"
  expand-icon="redeem"
  expand-label="Vouchers"
  headline="Buy a voucher"
  max-height="700"
></giftcard-widget>

Floating-button mode

Set presentation="expandable" to switch to a fixed floating-action button: a circular pill in one of six corners opens a docked panel with the shop inside. Useful when you want a persistent entry point that follows the visitor down the page.

<giftcard-widget
  location-id="535"
  locale="en"
  presentation="expandable"
  position="right-bottom"
  max-height="700"
  max-width="420"
  expand-label="Gift cards"
  expand-icon="card_giftcard"
  headline="Buy a voucher"
></giftcard-widget>

position controls both the FAB anchor and which edge the panel docks to. Allowed values:

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

expand-icon is a Material Icons ligature name (e.g. redeem, card_giftcard, celebration). Bundled via @fontsource/material-icons inside the embed — image URLs are not supported.

expand-theme switches between dark (default) and light styling for the button. The panel header follows the same theme — dark in default mode, light when expand-theme="light".

Inline-list mode

Leave presentation empty (or omit it) to drop the voucher list itself into the page flow. The widget takes the width of its parent and grows to the iframe's natural height, capped at max-height. Use this when you want a dedicated "Gift cards" landing section.

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

Attributes

Loading the script

Load widget.js once per page — anywhere in <head> or before the closing </body>. It registers the <giftcard-widget> custom element globally; subsequent <giftcard-widget> tags on the same page activate automatically.

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

Multiple widgets on one page are supported (e.g. an inline shop plus an expandable FAB elsewhere). Each iframe is isolated.

When you need direct SQL access to the POS — usually because APRO is installed on-premise alongside existing systems — the cash register database exposes a stable set of read-only views. They are intentionally shaped for the two most common consumers:

• On-premise integrations — accounting bridges, kitchen displays, stock management, loyalty engines — anything that runs inside the same network and wants a low-latency feed without going through REST.
• Existing BI workflows — Power BI, Tableau, Qlik, Metabase, Excel, native SQL Server Analysis Services — any tool that already understands SQL Server connections. Point the connector at the views and you get receipts, line items, payments and product master in the shape a data warehouse expects.

Views are read-only, queryable over the standard SQL Server protocol, and never join to operational tables that mutate under load — they are safe to drive dashboards and scheduled ETL jobs against.

Tip: SQL Views or Revenue API?
The SQL views and the Revenue API expose the same
underlying data — pick whichever fits the runtime:

- SQL Views (this page) — flat, relational, on-premise.
Perfect for ETL, Power BI / Tableau / Qlik / Metabase connectors and
any workflow that wants bulk access via SQL.
- Revenue API — served over the cloud endpoint my.apro.at, returns
a hierarchical JSON document with positions, payments and tax
already nested per receipt. Better for real-time system-to-system
integration, SaaS consumers and anything outside the local network.

Note
The read-only SQL user is provisioned per deployment. Ask your APRO
account manager to enable access for your tenant and to share the
server name, database, and credentials.

Overview

1. vw_Receipts

One row per business transaction. The TransactionType column distinguishes what the row represents; amounts are signed — reversal transactions (TransactionType = 4) return the booking with a negated amount so a plain SUM(TotalAmount) already nets them out.

Transaction types

Only transactions with a TransactionType in (1, 2, 3, 4, 5, 14, 24, 25) are exposed through this view. The authoritative mapping lives in vw_TransactionTypes and is also joined onto every row via TransactionTypeName.

2. vw_Receipt_Items

Line items. Join to vw_Receipts on ReceiptId / TransactionId. Values are signed the same way as the parent receipt.

3. vw_Payments

Payments recorded against receipts. Only settlements and their reversals are exposed (TransactionType in (3, 4, 5, 14, 24, 25)).

4. vw_Transactions

Light index of every transaction. Useful for watermark-based ETL (pulling only new rows since the last checkpoint).

5. vw_TransactionTypes

Lookup for every transaction type the POS emits.

6. vw_Bi_Export

The one-stop view for BI tools. Denormalized join of every turnover-relevant receipt with every line item, plus a comma-separated summary of the payment methods used on the receipt. Point Power BI or Tableau at this view and you have everything needed for revenue, margin, mix and payment-method dashboards without writing joins.

Columns are the union of vw_Receipts and vw_Receipt_Items (minus TransactionTypeId, which lives only on the receipt side), plus:

Power BI example

1. Get data → SQL Server database — server + database as provided.
2. Import or DirectQuery mode, using the read-only user.
3. Pick dbo.vw_Bi_Export as the fact table.
4. Optionally add dbo.vw_Transactions, dbo.vw_Payments, dbo.vw_products_and_categories as companion tables and relate on TransactionId / ProductId.

Import mode is normally sufficient — the views are already aggregated to transaction grain and refresh in seconds for a typical venue.

7. vw_products_and_categories

Product master with category. Useful as a dimension alongside vw_Bi_Export when the BI tool wants product names to stay stable even if historical rows predate a rename.

Only products where Geloescht = 0 (not soft-deleted) are included.

Example queries

Turnover per business day, split by tax rate — for a monthly KPI chart:

SELECT
  r.BusinessDay,
  ri.TaxName,
  SUM(ri.EffectiveAmount) AS net_turnover
FROM vw_Receipts AS r
JOIN vw_Receipt_Items AS ri ON ri.ReceiptId = r.Id
WHERE r.TransactionType IN (3, 4, 5)   -- settlements + reversals net out
  AND r.BusinessDay BETWEEN @from AND @to
GROUP BY r.BusinessDay, ri.TaxName
ORDER BY r.BusinessDay, ri.TaxName;

Top-10 products for the current month, using the BI view directly:

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

Cash vs. card split for a single business day:

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