Externe Bestellung API

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

Feld	Typ	Pflicht	Beschreibung
guid	string	—	Idempotenz-Schlüssel. Kommt derselbe guid zweimal, wird das Duplikat ignoriert.
locationId	int?	◻︎	Siehe Routing oben.
locationShortCode	string	◻︎	Siehe Routing oben.
spotId	int?	—	ID des Bestellziels (Tisch, Zimmer, Abhol-, Lieferstandort — alles Spots, nur unterschiedliche Typen). Entspricht spot.id der Externer-Katalog-API.
spotNumber	int?	—	Nummer des Spots, wenn die ID unbekannt ist. Aufgelöst über spot.number.
spotName	string	—	Fallback, wenn weder spotId noch spotNumber auflöst. Lookup über spot.name — bevorzugt einen Spot vom Typ Table, danach beliebiger Spot am Standort.
roomNumber	int?	—	Nummer des Zimmer-Spots für Hotel-/Zimmerabrechnungs-Flows. Aufgelöst gegen einen SpotType.Room-Spot über spot.number (verschoben um RoomNrSpotNrOffset des Standorts); Fallback auf spot.alternativeName gegen die rohe Zimmernummer. Bei Treffer wird spotId gesetzt (falls noch nicht vorhanden) und die Bestellung an die aktive Reservierung des Zimmers gebunden.
roomId	int?	—	Für zukünftige Erweiterungen reserviert. Wird aktuell akzeptiert, aber ignoriert — für ein Zimmer den spotId eines Room-Spots verwenden.
userInfo	UserInfo	✅	Wer bestellt — email ist Pflicht.
deliveryInfo	DeliveryInfo	—	Lieferadresse. Pflicht bei Zustellung.
takeaway	bool	✅	true für Mitnehmen, false für Vor Ort.
note	string	—	Freitext-Notiz des Gastes (Allergene, Sonderwünsche).
qrCode	string	—	Siehe Routing.
entries	Entry[]	✅	Bestellte Artikel.
preOrderTime	long?	—	Vorbestellzeitpunkt, Unix-Zeit in Millisekunden UTC.
shortCode	string	—	Abhol-/Lieferreferenz (z. B. zw1356).
tip	decimal?	—	Trinkgeldhöhe.
isPaid	bool	—	true, wenn die Bestellung bereits extern bezahlt wurde.
grandTotal	decimal?	✅	Summe aller Artikel + Tip. Wird serverseitig gegengeprüft.

Entry

Feld	Typ	Pflicht	Beschreibung
productNr	string	✅	Produktnummer in APRO.
name	string	—	Anzeigename — rein informativ; APRO vertraut auf productNr.
preOrderTime	long?	—	Vorbestellzeit pro Artikel.
quantity	double	✅	Bestellmenge.
price	double?	—	Übersteuert den Systempreis dieser Position (Rabatte, Kampagnen).
note	string	—	Artikel-Notiz (z. B. Ohne Zwiebeln).
addons	Addon[]	—	Zusatzoptionen.

Addon

Feld	Typ	Pflicht	Beschreibung
productNr	string	✅	Produktnummer des Addons.
name	string	—	Anzeigename.
quantity	double	✅	Menge.
price	double?	—	Übersteuert den Systempreis.

UserInfo

Feld	Typ	Pflicht	Beschreibung
firstName	string	—
lastName	string	—
email	string	✅	Kontakt-E-Mail für Belege und Status-Updates.
phone	string	—
locale	string	—	IETF-Locale, z. B. de-DE.
nickname	string	—	Kurzname für Besteller/Abholer.

DeliveryInfo

Feld	Typ	Beschreibung
name	string	Bezeichnung der Lieferadresse.
companyName	string	Firmenname.
city	string	Ort.
zip	string	PLZ.
street	string	Straße.
country	string	Land.
floor	string	Stockwerk.
stairway	string	Stiege.
door	string	Türe.
note	string	Hinweis zur Lieferadresse.

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.