Fiscal API

Diese API wird vom Kiosk oder der Kassensoftware benutzt, um Belege zu erzeugen und später wieder abzurufen. Der Zugriff läuft pro Cash Register über einen Bearer-Token plus eindeutigen Idempotency-Key.

1. Authentifizieren

Jeder Request sendet einen Bearer-Token und bei Schreibzugriffen einen Idempotency-Key.

Authorization: Bearer <api-secret>
Idempotency-Key: kiosk-42-order-2026-000123

2. Beleg erzeugen

POST auf den Cash-Register-Endpunkt mit Payload, Positionen, optionalen Zahlungen und Metadaten.

POST /api/v1/fiscal/cash-registers/{cashRegisterId}/receipts
Authorization: Bearer <api-secret>
Idempotency-Key: kiosk-42-order-2026-000123
Content-Type: application/json

3. Request Payload

`items` muss mindestens eine Position enthalten. Geldbeträge werden als Dezimalstring mit zwei Nachkommastellen gesendet.

{
  "externalTransactionId": "hobex-987654321",
  "occurredAt": "2026-07-12T17:30:00+02:00",
  "currency": "EUR",
  "receiptType": "standard",
  "items": [
    {
      "position": 1,
      "description": "Tageseintritt",
      "quantity": "1.000",
      "unit": "Stk",
      "unitPrice": "25.00",
      "grossAmount": "25.00",
      "vatRate": "20.00",
      "vatCategory": "standard"
    }
  ],
  "payments": [
    {
      "type": "card",
      "amount": "25.00",
      "reference": "hobex-987654321"
    }
  ],
  "metadata": {
    "kioskId": "KIOSK-01",
    "orderId": "ORDER-000123"
  }
}

4. Pflichtfelder und Werte

Diese Felder werden serverseitig validiert.

Top-level:
- occurredAt: ISO-8601 / DATE_ATOM, z. B. 2026-07-12T17:30:00+02:00
- currency: aktuell nur EUR
- receiptType: standard, cancellation, training, start, monthly, annual, closing, zero, collection, signature_outage, signature_recovery
- items: Array mit mindestens einem Eintrag

Item:
- position: positive Ganzzahl
- description: Text
- quantity: Dezimalstring mit bis zu 3 Nachkommastellen, z. B. "1.000"
- unit: Text, z. B. "Stk"
- unitPrice: Dezimalstring mit 2 Nachkommastellen
- grossAmount: Dezimalstring mit 2 Nachkommastellen
- vatRate: Dezimalstring mit 2 Nachkommastellen
- vatCategory: standard, reduced_1, reduced_2, zero, special

Optional:
- externalTransactionId
- payments[]
- metadata

5. curl Beispiel

curl -X POST "https://rksv.icc.at/api/v1/fiscal/cash-registers/{cashRegisterId}/receipts" \
  -H "Authorization: Bearer <api-secret>" \
  -H "Idempotency-Key: kiosk-42-order-2026-000123" \
  -H "Content-Type: application/json" \
  -d '{
    "externalTransactionId": "hobex-987654321",
    "occurredAt": "2026-07-12T17:30:00+02:00",
    "currency": "EUR",
    "receiptType": "standard",
    "items": [
      {
        "position": 1,
        "description": "Tageseintritt",
        "quantity": "1.000",
        "unit": "Stk",
        "unitPrice": "25.00",
        "grossAmount": "25.00",
        "vatRate": "20.00",
        "vatCategory": "standard"
      }
    ],
    "payments": [
      {
        "type": "card",
        "amount": "25.00",
        "reference": "hobex-987654321"
      }
    ],
    "metadata": {
      "kioskId": "KIOSK-01",
      "orderId": "ORDER-000123"
    }
  }'

Die Antwort enthält zusätzlich receiptUrl, zum Beispiel https://rksv.icc.at/123456789012. Ein GET auf diese öffentliche URL liefert die JSON-Daten des QR-Codes.

6. Wiederholen ohne Duplikate

Bei Netzfehlern denselben Request mit exakt gleichem Idempotency-Key erneut schicken.

7. Cash Register anlegen

Cash Registers können im Admin-Bereich oder per Console-Command provisioniert werden.

GET /admin/cash-registers
php bin/console app:cash-register:create system kiosk-01 "Kiosk 01"