Slopestars API Doku für Bergfex Gutscheineinlösung

Version: 0.1
Überblick

Begriffsdefinition:
Activation Partner: Ein Partner bei dem Gutscheine erworben werden können, z.B. eine Supermarktkette wie Billa
Redemption Partner: Ein Partner der Leistungen für die Gutscheine erbringt, z.B. ein Skigebiet. Also der Leistungserbringer, wie z.B. Mayrhofner Bergbahnen
Transaction Partner: Ein Partner der autorisiert ist, für einen Redemption Partner Gutscheine einzulösen, z.B. ein Online-Shop von elements, starjack, ski amade. Online-Shops sind die Zielgruppe für dieses Dokument.

Das Gutscheinsystem für die Transaction Partner hat eine REST Schnittstelle mit HMAC Authentifizierung, die im Folgenden näher beschrieben wird.

REST Aufrufe

Es gibt folgende Aufrufe:
• GET /api/shop/
Liefert den ganzzahligen Restwert des Gutscheins mit Status 200.

• POST /api/shop
Aktualisiert den Gutschein. Im Body muss ein JSON Objekt in folgendem Format mitgeliefert werden:
{ redemptionCode: „“, amount: , transactionId: „“ }
Der Betrag kann auch negativ sein, z.B. für Stornos.

Die Transaktionsnummer ist eine vom Shop mitzuliefernde Nummer, welche die Transaktion, bei der der Gutschein verwendet wurde, eindeutig identifiziert. Das dient zur Nachvollziehbarkeit von Buchungen. Soll ein Storno durchgeführt werden, dann muss als Transaktionsnummer die gleiche Nummer mitgesendet werden, die auch zum Einlösen verwendet wurde.
Der Aufruf liefert Status 200 bei Erfolg und Status 400 bei Fehlern. Folgende Fehlercodes können im Body zurückgeliefert werden:
• Error = 1
• BadSignature = 2
• ShopNotFound = 3
• PartnerNotFound = 4
• PartnerAccessDenied = 5
• RedemptionCodeNotFound = 6
• RedemptionCodeAndPartnerNotMatching = 7
• ShopPublicKeyHttpHeaderMissing = 8
• ShopHashHttpHeaderMissing = 9
• PartnerPublicKeyHttpHeaderMissing = 10
• InsufficientFunds = 11
• CancellationAmountOverflow = 12
• InvalidAmount = 13
• TransactionIdMissing = 14
• CancellationWithoutRedemption = 15

Authentifizierung, Signatur

Damit festgestellt werden kann, ob ein Aufruf gültig ist, müssen im HTTP Header folgende Informationen mitgeliefert werden.
X-Shop-Public-Key: Identifiziert den Transaction Partner
X-Partner-Public-Key: Identifiziert den Redemption Partner zu dem der Gutschein-Code gehört
X-Shop-HMAC-SHA256: Der Hash mit dem der Aufruf signiert wurde

Jeder Transaction Partner bekommt einen Zugang zu einem Backend, in dem der Public Key und ein Secret Key abgerufen werden können. Der REST Aufruf muss dann mit einem HMAC SHA256 Hash unter Verwendung des Secret Key signiert werden.
Ein Beispielcode zum Signieren eines Aufrufs in C# oder PHP kann bei Bedarf zur Verfügung gestellt werden.