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":"2018-11-18 13:40:33",
   "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":"2018-11-18 13:40:33",
   "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":"2018-11-18 13:40:33",
   "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":"2018-11-18 13:40:33",
   "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":"2018-11-18 13:40:33",
   "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