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:

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

Beispielantwort

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 + befüllter errors-Array sagt, warum der Gutschein gerade nicht einlösbar ist. Häufige Codes:

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

Beispielanfrage

POST /voucherservice/api/v1/vouchers/gifts

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

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

Beispielanfrage

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

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

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

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

Beispielanfrage

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

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

Download: voucher-booking-request.json

Beispielantwort

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