Api

API zur Ansteuerung des Zutrittssystems

Einleitung

Diese API dient zur Kommunikation zwischen dem Kassensystem (KS) und dem Zutrittssystem (ZS).
Dabei stellt das KS eine Anfrage an das ZS um eine Freigabe für das gewünschte Produkt zu erhalten.
Der Rückgabeparameter ist ein Objekt mit Kundentype/n-Array/s mit deren Ticketnummern

Securehash erstellen

Der Securehash setzt sich aus dem request-JSON-String sowie einem Secret ("topsecret") zusammen.
{"request_id":125,"timestamp":"2015-11-28 10:55:44","count":1,"product_id":[10]}topsecret
Anschließend wird mittels sha256 daraus der Hash gebildet.
fc5e686568da5dc600d931a581846cbfdfdd568e516b1b4d91731b098a25fb70

Headerinformationen

Im Header wird der Secure-Hash (cashpoint-hash) sowie zur Identifikation der Kassa die Kassen-ID (cashpoint-id) übermittelt
    ...
    Content-Type: application/json
    cashpoint-id: 1
    cashpoint-hash: fc5e686568da5dc600d931a581846cbfdfdd568e516b1b4d91731b098a25fb70
    ...

Anfrage nach Zutritts-ID(s)

URI HTTP Methode MIME-Type
https://access.rmg-online.at/api/getids/ POST Content-Type: application/json

Request

Das Request-Array muss in einen JSON-String umgewandelt werden und wird mittels POST übertragen

Einfacher Request

Bei dem nachfolgenden Request wird eine Anfrage mit mit einer product_id übergeben. Dabei sind die Eigenschaften der Id 10 am Zutrittssystem hinterlegt.
Annahme ist, dass bei diesem Produkt eine Familienkarte hinterlegt ist und dadurch

  • 2 Erwachsenen-Tickets
  • 3 Kindertickets sowie
  • 1 Pensionistenticket
erstellt werden und an das Kassensystem zurückgeschickt wird (siehe Response).
optional: Mit dem Parameter active kann festgelegt werden, ob die erstellen Tickets aktiviert (1 = Default) oder gesperrt (0) sind.
Json

{  
   "request_id":123,
   "timestamp":"2019-07-21 19:35:44",
   "count":1, (optional [int])
   "product_id":[10], 
   "active": 1, (optional [0/1])
   "start_datetime": "YYYY-mm-dd HH:ii:ss" (optional - Ticket gilt ab...)
   "end_datetime": "YYYY-mm-dd HH:ii:ss" (optional - Ticket gilt bis...)
}

Erweiterter Request

Zusätzlich zum einfachen Request kann entweder die gewünschte Anzahl an Kundentypen-Tickets (Option 1), bzw. die Kundentypen mit den vordefinierten Ticketnummern (Option 2) angefordert werden.
Durch angabe der Ticketnummern, werden diese versucht am ZS zu registrieren und dem gewünschten Kundentypen zugewiesen. Des weiteren erhalten die Ticketnummern die product_id-Eigenschaften
Json
{
   "request_id":123,
   "timestamp":"2019-07-21 19:35:44",
   "count":1,
   "product_id":[10] 
}
Diese Anfrage liefert für die Produkt-ID 10 die hinterlegte Anzahl an Tickets. Count ist der Multiplikator der hinterlegten Anzahl im Tickettype.
{
   "request_id":123,
   "timestamp":"2019-07-21 19:35:44",
   "count":1,
   "product_id":[10],
   "customers":{  
         "adult":2,
         "children":2,
         "seniors":1
   }
}
Diese Anfrage erstellt für die Produkt-ID 10 genau die Anzahl der angeforderten Tickets. In diesem Fall 2 Erwachsene, 2 Kinder und einen Pensionisten. Als Rückgabewert werden die Ticketcodes zurückgegeben.
{
   "request_id":123,
   "timestamp":"2019-07-21 19:35:44",
   "count":1,
   "product_id":[10],
   "tickets": {
        "adult":[
            "1010000001670",
            "1010000001671",
            "1010000001672"
        ],
        "children":[
            "1010000001673",
            "1010000001674",
            "1010000001675"
        ]
   }
}
Diese Anfrage erstellt für die Produkt-ID 10 die gewünschten Tickets mit definiertem Code und Personengruppe.
Variable Beschreibung Default-Wert Erforderlich
request_id Eindeutige ID vom KS NULL JA
timestamp Zeitpunkt der Anfrage timestamp NEIN
product_id Produkt Identify Int[] JA
count Anzahl der gewählten Produkte * option.customers 1 NEIN
options Spezielle Optionen für die Anfrage Default NEIN
options.duration Zeitraumberechtigung Default NEIN
customers Kundentype und Anzahl Default NEIN

Response

{  
   "request_id":123,
   "error_id":0,
   "timestamp":"2019-07-21 19:35:44",
   "customers":{  
      "adult":[  
         "1234567890128",
         "1234567890135"
      ],
      "children":[  
         "1234567890142",
         "1234567890159",
         "1234567890166"
      ],
      "seniors":[  
         "1234567890173"
      ]
   }
}
error_id Beschreibung
0 Kein Fehler
1 Keine Daten übermittelt
2 Daten ungültig
3 Signatur ungültig
4 Produkt nicht gefunden
5 ungültige Optionen
6 duration erforderlich
7 customers erforderlich
8 Zutritts-ID fehler

Tickets stornieren

Tickets werden indirekt über die request_id storniert. Somit wird nicht ein einzelnes Ticket entwertet, sondern alle referenzierenden Tickets zur request_id.
URI HTTP Methode MIME-Type
https://access.rmg-online.at/api/stornorequest/ POST Content-Type: application/json

Verfügbare Tickettypen abfragen

Liefert ein Array der verfügbaren Tickettypen

URI HTTP Methode MIME-Type
https://access.rmg-online.at/api/gettickettypes/ GET Content-Type: application/json

Kartenguthaben

In diesem Abschnitt werden die Kartenguthaben behandelt. Dabei ist es möglich einer Karte einen Float-Wert als Buchung anzuhängen (+XY = Aufbuchung: -XY = abbuchung). Des weitern kann der "Kontostand" abgefragt werden

Wert auf oder Abbuchen

URI HTTP Methode MIME-Type
https://access.rmg-online.at/api/accountcrediting/ POST Content-Type: application/json

Request

{
   "request_id":1563730544,
   "timestamp":"2019-07-21 19:35:44",
   "ticket": "0000215094579742",
   "text": "Gastronomie-Konsumation",
   "reference_id": "1551790167",
   "value": -8,
   "json": 
   {
	"type": "product",
	"count": 1,
	"product":
	{
		"tax": 10,
		"ean": "5830236184935",
		"price": 8,
		"name": "Wienerschnitzel mit Salat"
	}
   }
}
Werte im Feld json werden vom System nicht beachtet sondern nur als json interpretiert und gespeichert

Response

{
  "error_id": 0,
  "ticket": "0000215094579742",
  "message": "value -8 is set to ticket 0000215094579742",
  "timestamp": "2019-07-21 19:35:46",
  "request_id": 1563730544
}

"Kontostand" abfragen

URI HTTP Methode MIME-Type
https://access.rmg-online.at/api/getaccountamount/ POST Content-Type: application/json

Request

{
   "request_id":1563730544,
   "timestamp":"2019-07-21 19:35:44",
   "ticket": "0000215094579742",
}

Response

Als Rückgabewert(e) erhält man wieder den Error-Code sowie:
  • Anzahl aller Transaktionen transactions_count (int)
  • Anzahl aller Aufbuchungen transactions_add_count (int)
  • Anzahl aller Abbuchungen transactions_sub_count (int)
  • Summe der Aufbuchungen transactions_add_sum (float)
  • Summe der Abbuchungen transactions_sub_sum (float)
  • den "Kontostand" transactions_total (float)
  • Zeitstempel der letzten Transaktion last_timestamp
{
  "error_id": 0,
  "ticket": "0000215094579742",
  "valueaccount": {
    "transactions_count": 3,
    "transactions_add_count": 0,
    "transactions_sub_count": 3,
    "transactions_add_sum": 0,
    "transactions_sub_sum": -27.6,
    "transactions_total": -27.6,
    "last_timestamp": "2019-03-05 13:49:27",
    "transactions": [
      {
        "type": "A",
        "text": "Gastronomie-Konsumation",
        "reference_id": "1551790048",
        "value": "-6.6",
        "json": {
          "type": "product",
          "count": 3,
          "product": {
            "tax": 20,
            "ean": "1234567890123",
            "price": 2.2,
            "description": "Coca Cola 0,33 l"
          }
        }
      },
      {
        "type": "A",
        "text": "Gastronomie-Konsumation",
        "reference_id": "1551790126",
        "value": "-13",
        "json": {
          "type": "product",
          "count": 2,
          "product": {
            "tax": 10,
            "ean": "8959302834138",
            "price": 6.5,
            "description": "Mittagsmenü 1"
          }
        }
      },
      {
        "type": "A",
        "text": "Gastronomie-Konsumation",
        "reference_id": "1551790167",
        "value": "-8",
        "json": {
          "type": "product",
          "count": 1,
          "product": {
            "tax": 10,
            "ean": "5830236184935",
            "price": 8,
            "description": "Wienerschnitzel mit Salat"
          }
        }
      }
    ]
  },
  "timestamp": "2019-07-21 19:35:47",
  "request_id": 1563730544}