Cinuru REST API

Allgemeines

Auth-Token

Zur Nutzung der Cinuru REST API benötigen Sie einen JSON-Web-Token (JWT) von uns. Diesen senden wir Ihnen gerne zu.

Dieser Token muss im Request Header gesetzt werden und zwar wie folgt:

Feld-Name: Authorization

Feld-Wert: 'Bearer #TOKEN#'

Dabei ist #TOKEN# durch den JWT zu ersetzen.

Content-Type

Die Cinuru REST API akzeptiert und sendet Daten im JSON Format. Dazu ist es nötig, dass der Content-Type im Request Header auf application/json gesetzt ist.

Datentypen

In der API-Beschreibung sind die Typen wie folgt angegeben:

String ist ein Text nicht begrenzter Länge. Kann null sein.

Number eine Zahl, kann sowohl Float als auch Integer Werte enthalten (wird ggf. gesondert angegeben). Kann null sein.

Boolean entweder true, false oder null

Date Datum im ISO_8601 Format. Wichtig ist, dass die Zeitzone entweder UTC ist, oder als Offset mit angegeben wird. Kann null sein.

TMS-Integration

POST: /preshow-lists

Der POST Endpoint /preshow-lists ermöglicht es, Trailer-Listen an Cinuru zu senden. Er erwartet Daten in folgendem Format:

{
    "centerName": String
    "centerId": String
    "screenings": [
        {
            "id": String
            "start": Date
            "end": Date
            "auditoriumId": Date
            "movieId": String
            "movieTitle": String
            "cplIds": [
                String
            ]
        }
    ]
}

Beispieldaten:

{
    "centerName": "Test Kino Erlangen",
    "centerId": "xy123",
    "screenings": [
        {
            "id": "Vorstellung987891",
            "start": "2018-06-04T19:39:22.507Z",
            "end": "2018-06-04T21:39:22.507Z",
            "auditoriumId": "Saal 2",
            "movieId": "To be defined",
            "movieTitle": "Avengers - Infinity War",
            "cplIds": [
                "Rampage_TLR-F1_F_DE-XX_DE_51_2K_WR_20171113_DTU_IO",
                "Skyscraper_TLR-1_F_DE-XX_DE_51_2K_UPIG_20180206_TM_IO"
            ]
        }
    ]
}

Kassensystem-Integration

Die vorliegende API ist ein Entwurf. Sie wurde entworfen mit der Vorgabe, dass sämtliche API-Funktionalitäten Cinuru-seitig realisiert werden.

Aus unserer Sicht ist es sinnvoller, dass viele der hier angegebenen Funktionalitäten von einer API des Kassensystems bereitgestellt werden. Dies betrifft die Synchronisation der Bonuskarten, des Filmprogramms oder der Artikel des Kassensystems. Insbesondere die Synchronisation der Bonuskarten dürfte mit dem hier vorgestellten Verfahren mehr Anpassungen im Kassensystem verursachen.

Die folgende API ist ein Vorschlag für eine Umsetzung. Bitte teilen Sie uns Anpassungswünsche mit.

Bonuspunkte buchen und einlösen

POST: /book-articles

Dieser Endpoint dient dem Kassensystem dazu Bonuspunkte auf ein Cinuru-Konto zu buchen.

Es sendet dazu zu jedem Einkauf, bei dem mindestens ein Nutzer Cinuru-Punkte sammelt, folgende Informationen an Cinuru:

{ "bookingId": String
        "centerId":String
        "tickets":[{
            "ticketId":String
            "userQr":String
            "ticketPrice":Number
            "ticketCategory": String
            "screeningId":String

        }]
        "otherArticles":[{
            "userQr":String
            "price":Number
            "articleId": String
        }
    ]
}

POST: cancel

Dieser Endpunkt dient dazu Buchungen zu stornieren. canceledBookings dient dazu einen kompletten Einkauf zu stornieren, wähend canceledTickets dazu dient einzelne Tickets zu stornieren. Ggf. wird nur eines der beiden Felder vom Kassensystem genutzt.

{
    "canceledBookings":
    [{
        "bookingId":String
    }],
    "canceledTickets":
    [{
        "ticketId":String
    }]

}

GET: /voucher-info/<voucher-qr>

Um Cinuru-Bonuspunkte einzulösen kann der Cinuru-Nutzer in seiner App diese in Gutscheine (voucher) eintauschen. Nachdem der Nutzer in seiner App einen solchen Gutschein erworben hat, soll er diesen an der Kasse einlösen können. Dazu soll das Kassensystem den QR-Code des Gutscheins scannen und anschließend die zugehörigen Informationen bei der Cinuru-API abfragen. Die Informationen sollen dem Kassenpersonal angezeigt werden und anschließend soll es möglich sein den Gutschein entweder einzulösen oder den Einlösevorgang abzubrechen.

Die Gutscheindetails können unter dem Endpoint voucher-info/:voucher-qr abgefragt werden, folgende Informationen werden zurückgesendet.

{
    "voucherId":String
    "voucherTitle":String
    "voucherText":String
    "valid":Boolean
    "invalidReason":String
    "voucherImageUrl":String
}

POST: /redeem-voucher

Zum Einlösen (Entwerten) eines Gutscheins dient der Endpoint redeem-voucher. Er erhält die voucherId des einzulösenden Gutscheins und gibt ein Statusobjekt mit den Werten success und im Falle eines Fehlers einen errorText.

{
    "voucherId":String
    "centerId":String
}

Antwort:

{
    "success":Boolean
    "errorText":String
}

Bezahl- und Bonuskarten synchronisieren

Im Kassensystem vorhandene Bezahl- und Bonuskarten (bonusCard) sollen zukünftig mit der Cinuru-App synchronisierbar sein.

Dazu ist es wichtig, dass die Guthabenstände (Geld/Punkte) synchronisiert werden können.

Wir glauben, dass es einfacher ist, wenn das Kassensystem eine API zur Abfrage und zum Updaten der Bonuskarten zur Verfügung stellt.

In dem vorliegenden Architekturentwurf ist es notwendig, dass das Kassensystem regelmäßig Updates an Cinuru sendet.

Die Synchronisierung aller vorhandenen Karten soll in regelmäßigen Abständen (z.B. täglich) erfolgen. Darüber hinaus sollen Änderungen (neue Karte, Änderung des Guthabens) möglichst sofort gesendet werden.

POST /bonus-card-statuses

Dieser Endpoint dient dazu, dass das Kassensystem die Statusinformationen der Bonuskarten an Cinuru übermitteln kann. Dieses ist wichtig für eine initiale Synchronisation.

{
    "bonusCards":[
        {
            "bonusCardId":String
            "balanceMoney":Number
            "balancePoints":Number
            "validUntil": Date
        }
    ]
}

GET /bonus-card-statuses

Dieser Endpunkt dient dazu, dass Cinuru Änderungen and den Bonuskarten (z.B. Erhöhung des Punktestandes) an das Kassensystem übermitteln kann. Je nach Architektur des Kassensystems kann es sinnvoller sein den Endpunkt POST: bonus-card-transactions anzusprechen, welcher mehr Details enthält.

{
    "bonusCards":[
        {
          "bonusCardId":String
          "balanceMoney":Number
          "balancePoints":Number
          "validUntil": Date
      }
    ]
}

POST /bonus-card-transactions

Mit diesem Endpunkt kann das Kassensystem Bonuskartentransaktionen (Veränderung des Punktestandes/Geldwerts) an Cinuru übermitteln.

{
    "transactions":[
        {
            "bonusCardId":String
            "moneyDifference":Number
            "pointsDifference":Number
            "bookingReasonId":String
            "bookingReasonDescription":String
            "timestamp": Date
        }
    ]
}

GET bonus-card-transactions?since=<Date>

Dieser Endpoint dient dazu, dass Cinuru Änderungen an den Bonuskarten (z.B. Erhöhung des Punktestandes) an das Kassensystem übermitteln kann. Dieser Endpunkt sollte regelmäßig (z.b. minütlich) gepollt werden.

{
    "transactions":[
        {
            "bonusCardId":String
            "moneyDifference":Number
            "pointsDifference":Number
            "bookingReasonId":String
            "bookingReasonDescription":String
            "timestamp": Date
        }
    ]
}

GET new-bonuscards?since=<Date>

Dieser Endpoint dient dazu, dass Cinuru neue Bonuskarten an das Kassensystem übermitteln kann. Dieser Endpunkt sollte regelmäßig (z.b. minütlich) abgefragt (gepollt) werden.

{
    "bonusCards":[
        {
            "bonusCardId":String
        }
    ]
}

Filmprogramm synchronisieren

POST /program

{
    "centerId":String
    "movies"[{
        "movieId":String
        "edi":String
        "title":String
        "releaseYear":Number
        "onlineTicketingIdentifier":String
        "screenings":{
            "id":String
            "startDate": Date
            "endDate": Date
            "auditoriumId":String
            "flag3d":Boolean
            "flagOV":Boolean
            "flagOMU":Boolean
            "flagLive":Boolean
            "onlineTicketingUrl":String
            }
        }
    ]
}

Artikel des Kassensystems synchronisieren

Um Punkte für gekaufte Tickets und Concessions vergeben zu können muss Cinuru die im Kassensystem angelegten Artikel und Kategorien kennen. Das Kino hat dann innerhalb von Cinuru die Möglichkeit, je nach Kategorie oder Artikel unterschiedlich Bonuspunkte zu vergeben.

POST /article-catalog

    {
            "centerId":String
            "categories":[{
                "id":String
                "name":String
                "subCategoryOf":String
            }]
            "article"{
                "id":String,
                "categoryId":String
                "name":String
                "price":Number
                "description":String
            }
        }

subCategoryOf enthält die id einer anderen Kategorie oder null.

Online Ticketing

Cinuru-Nutzer sollen auch Bonuspunkte für online gekaufte Tickets erhalten:

Die Cinuru-App verweist auf das bestehende Online-Ticketing der Kinos. Um Käufe zuordnen zu können, soll es möglich sein, dass die Cinuru-App auf das Online Ticketing verweist und einen Identifier (OutlinkId) mitsendet. Nach abgeschlossener Buchung sollen die zugehörigen Buchungsdaten (Tickets, etc. ) zusammen mit dem Identifier an Cinuru gesendet werden. Wird die Buchung später storniert, muss diese Information ebenfalls übermittelt werden.