Gutscheine API

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:

Feld	Typ	Beschreibung
`id`	GUID	Interne APRO-Gutschein-ID (URL-Parameter).
`voucherCode`	string	Lesbarer Code auf der Karte/dem Beleg.
`gift.amount`	integer	Ursprünglicher Nennwert (Minor Units).
`gift.balance`	integer	Verfügbares Guthaben (Minor Units).
`gift.maxAmount`	integer \| null	Aufladelimit; `null` = unbegrenzt.
`codeId`	string \| null	Optionale Zweit-ID.
`startDate`	ISO 8601 \| null	Vor diesem Zeitpunkt nicht gültig.
`expirationDate`	ISO 8601 \| null	Nach diesem Zeitpunkt nicht gültig.
`enabled`	bool	`false` = manuell gesperrt.
`comment`	string \| null	Freitext-Notiz.
`categoryId`	integer	Gutscheinkategorie (Ausgabekanal).
`categoryName`	string	Kategoriename.
`categoryNrOfTimesRedeemablePerUnit`	integer \| null	Einlöse-Limit auf Kategorie-Ebene.
`categoryExternalPaymentProviderId`	string \| null	Verweis auf externen Payment-Provider.
`createdAt`	ISO 8601	Ausgabezeitpunkt.
`discriminator`	string	`"GiftVoucherDto"` für Gutschein-Karten.

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

Name	Typ	Pflicht	Beschreibung
`voucherCode`	string	✅	Der auf dem Gutschein aufgedruckte Code.

Beispielantwort

{
  "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:

Fehler	Bedeutung
`NotFound`	`voucherCode` existiert nicht.
`Expired`	`expirationDate` überschritten.
`NotYetStarted`	Vor `startDate`.
`Disabled`	`enabled = false`.
`NoBalance`	`balance == 0`.
`CategoryCapReached`	`categoryNrOfTimesRedeemablePerUnit` erschöpft.

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

Feld	Typ	Pflicht	Beschreibung
`categoryId`	integer	✅	Gutscheinkategorie.
`voucherCode`	string	✅	Aufgedruckter Code. Muss eindeutig sein.
`comment`	string	—	Freitext-Notiz.
`gift.amount`	integer	✅	Nennwert in Minor Units.
`gift.maxAmount`	integer	—	Aufladelimit.
`clientType`	string	✅	Kennung des aufrufenden Systems. Wird von APRO für deine Integration vergeben — siehe clientType.
`clientContext`	string (JSON)	—	Serialisierte JSON-Zusatzinfo (Outlet etc.).
`startDate`	ISO 8601	—	Gültig ab.
`expirationDate`	ISO 8601	—	Gültig bis.

Beispielanfrage

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

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

Feld	Typ	Pflicht	Beschreibung
`redemption.amount`	integer	✅	Abzubuchender Betrag in Minor Units.
`clientReference`	string	—	Opake Trace-Zeichenkette (z. B. `"{ \"waiterId\": 10 }"`). Wird persistiert.
`clientContext`	string (JSON)	—	Zusatzinfo.
`comment`	string	—	Freitext-Notiz.
`clientType`	string	✅	Kennung des aufrufenden Systems. Wird von APRO vergeben — siehe clientType.

Beispielanfrage

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

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

Feld	Typ	Pflicht	Beschreibung
`amount`	integer	✅	Gutzubuchender Betrag in Minor Units. `gift.maxAmount` beachten.
`clientReference`	string	—	Opake Trace-Zeichenkette.
`clientType`	string	✅	Kennung des aufrufenden Systems. Wird von APRO vergeben — siehe clientType.
`clientContext`	string (JSON)	—	Zusatzinfo.
`comment`	string	—	Freitext-Notiz.

Beispielanfrage

{
  "amount": 1000,
  "clientReference": "{ \"waiterId\": 10 }",
  "clientType": "<von-apro-vergeben>",
  "clientContext": "{\"outletId\":\"231231\"}",
  "comment": "Aufladung nach Guthabenzukauf"
}

Download: voucher-booking-request.json

Beispielantwort

{
  "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.