Dokumentation

1Einführung

Die Analytics-Funktion hilft Händlern, ihre Transaktionen in PostFinance Checkout schnell zu analysieren und Einblicke in ihre Geschäftsentwicklung zu erhalten.

Durch strukturierten Zugriff auf ihre Daten können sie vorausschauend auf Kundenbedürfnisse reagieren.

Berichte lassen sich durch SQL-Abfragen generieren. Die gesamte Datenanalyse basiert auf PrestoDB, einer Open-Source-SQL-Abfrage-Engine von Amazon Athena.

Das Analytics Schema beschreibt die aus der PostFinance Checkout exportierten Datenstrukturen, die über die Portal-Benutzeroberfläche und die REST-API abgefragt werden können.

2Übersicht

Die Übersicht aller ausgeführten Analytics-Abfragen finden Sie im Account unter Account > Analytics > Abfragen.

Liste der ausgeführten Analytics-Abfragen
Figure 1. Die Liste der ausgeführten Analytics-Abfragen ist im Account sichtbar.

2.1Abfrage senden

Händler können eine Abfrage im jeweiligen HändlerAccount unter Account > Analytics > Abfrage senden senden.

Analytics-Abfrage senden
Figure 2. Die Abfrage kann durch Klicken auf die Schaltfläche Senden gesendet werden.

Eine gesendete Abfrage wird asynchron verarbeitet. Die Abfrageausführung hat zunächst den Status PROCESSING, und es sind keine Details verfügbar. Sobald die Abfrageausführung verarbeitet und abgeschlossen ist, ändert sich der Status in SUCCESS, und die Abfragedetails können abgerufen werden.

Schlägt die Abfrageausführung fehl oder wird sie vor Abschluss abgebrochen, ändert sich der Status in FAILED bzw. CANCELLED, und es sind keine detaillierten Abfrageinformationen verfügbar.

Informationen zu den Einschränkungen beim Senden der Abfrage finden Sie unter Zugriffskontrolle und Berechtigungen.

2.1.1Assets

Auf der linken Seite des Abfrage-Editors befindet sich das Assets-Panel, eine zentrale Anlaufstelle zum Auffinden und Verwalten Ihrer Daten. Dieses Panel zeigt Folgendes an:

  • Verfügbare Tabellen: Eine alphabetisch sortierte Liste der für Sie zugänglichen Tabellen und Ansichten (basierend auf Ihren Benutzerberechtigungen).

  • Favoriten: Eine kuratierte Sammlung gespeicherter Abfragen für den schnellen Zugriff.

  • Beispiele: Eine Sammlung von Beispielabfragen zur Inspiration.

  • Berechtigungserkennung: Tabellen werden automatisch basierend auf Ihren Zugriffsrechten gefiltert.

Analytics-Abfrage-Assets
Figure 3. Abfrage-Editor-Assets für eine einfache Bedienung.

2.2Wiederkehrende Abfrageübermittlung ausführen

Um Analytics-Abfragen für die regelmäßige Ausführung zu planen, verwenden Sie die Funktion Wiederkehrende Abfrage.

Schritt 1: Wiederkehrende Abfrage erstellen

Schritt 2: Abfrageberechtigungen konfigurieren

  • Wiederkehrende Abfragen übernehmen die Berechtigungen von der der Abfrage zugewiesenen Benutzer-ID. Dies gewährleistet einen konsistenten Datenzugriff sowohl für reale als auch für Anwendungsbenutzer.

  • Wichtig: Die Benutzer-ID bestimmt den Sicherheitskontext für die Abfrageausführung.

Schritt 3: Startdatum festlegen

  • Das Startdatum gibt an, wann die Abfrage ausgeführt wird. Klicken Sie auf Erstellen.

  • Hinweis: Im nächsten Schritt muss ein gültiger Zeitplan eingerichtet werden, damit die Abfrage ausgeführt werden kann.

Schritt 4: Ausführungszeitplan festlegen

2.2.1Tagesplan

  • Führt die Abfrage zu einer festgelegten Uhrzeit an festgelegten Wochentagen aus.

  • Beispiel: Ausführung jeden Montag um 9:00 Uhr.

Visuelle Referenz:

Analytics-Wiederkehrende tägliche Abfrage planen
Figure 4. Abfrageeditor-Assets für eine einfache Bedienung.

2.2.2Monatsplan

  • Führt die Abfrage zu einer festgelegten Uhrzeit an festgelegten Tagen aus.

  • Beispiel: Ausführung am 15. jedes Monats.

Visuelle Referenz:

Planen Sie eine monatliche Analytics-Abfrage
Figure 5. Analytics-Wiederkehrende monatliche Abfrage planen.

2.2.3Wichtige Hinweise zu monatlichen Zeitplänen

Fallback auf letzten Tag:

Wenn Ihre Abfrage am letzten Tag des Monats ausgeführt werden muss, verwenden Sie diese Funktion:

  1. Wählen Sie den 31 als Tag.

  2. Aktivieren Sie die Option Fallback am letzten Tag verwenden.

    • Die Abfrage wird automatisch so angepasst, dass sie am letzten gültigen Tag kürzerer Monate ausgeführt wird (z. B. 28. Februar, 30. April).

Visuelle Referenz:

Senden Sie eine wiederkehrende Analytics-Abfrage
Figure 6. Senden Sie eine wiederkehrende Analytics-Abfrage.

2.2.4Warum das wichtig ist

  • Konsistente Berechtigungen: Wiederkehrende Abfragen werden im gleichen Sicherheitskontext wie Benutzerkonten ausgeführt, wodurch sichergestellt wird, dass der Datenzugriff den Richtlinien Ihres Unternehmens entspricht.

  • Flexible Planung: Tägliche und monatliche Optionen ermöglichen eine präzise Kontrolle über die Ausführungszeitpunkte von Abfragen. Mit einer Fallback-Logik können Sie Sonderfälle wie kürzere Monate bewältigen.

  • Effizienz: Automatisieren Sie wiederkehrende Aufgaben, um Zeit zu sparen und manuellen Aufwand zu reduzieren.

2.3Details zur Abfrageausführung

Beim Öffnen einer bestimmten Abfrageausführung werden detaillierte Informationen angezeigt, darunter die übermittelte SQL-Abfrage, ein Download-Link zur Ergebnisdatei (im CSV-Format) und verfügbare Aktionen für die Abfrage (z. B. Abbrechen der Abfrageausführung).

Details zur Ausführung von Analytics-Abfragen
Figure 7. Details zur Abfrageausführung.

2.4Abfrageausführung abbrechen

Eine Abfrageausführung im Status PROCESSING kann durch Klicken auf die Schaltfläche „Ausführung abbrechen“ in der Detailansicht der Abfrageausführung (Details zur Abfrageausführung) abgebrochen werden.

Wenn die Abfrageausführung bereits einen endgültigen Status erreicht hat (SUCCESS, FAILED oder CANCELLED), wird der Abbruchversuch ignoriert.

3Die REST-API für Analytics-Abfragen

Analytics Queries REST API dient zur Verwaltung der Ausführung von Analytics-Abfragen. Sie ermöglicht es Nutzern, Abfrageanfragen zu senden, Ergebnisse im CSV-Format abzurufen, die Abfrageausführung zu überwachen und laufende Abfragen abzubrechen.

Die vollständige API-Referenz finden Sie in der Analytics Queries REST API-Dokumentation.

3.1Beispiel: Kunden nach kumulierten Transaktionsbeträgen auflisten

In diesem Beispiel wird eine Abfrage ausgeführt, um Kunden sortiert nach dem Betrag aufzulisten, den sie im Händlerbereich ausgegeben haben. Mithilfe des Analytics Schema erstellen wir die folgende PrestoDB-SQL-Abfrage, die die Summe der Transaktionsbeträge gruppiert nach Kunden berechnet:

SELECT SUM(completedamount) AS total, customerid
FROM transaction
GROUP BY customerid
ORDER BY total DESC;
Note
Tabellen- und Spaltennamen müssen in Kleinbuchstaben angegeben werden, da sie intern kleingeschrieben werden, obwohl SQL-Schlüsselwörter, -Klauseln und reservierte Schlüsselwörter (wie SELECT) nicht zwischen Groß- und Kleinschreibung unterscheiden.

3.2Abfrageausführung absenden

Eine Abfrageanforderung kann mit der Methode Submit Query Execution Request (HTTP POST) zur Ausführung abgeschickt werden. Der Anfragetext sollte eine Analytics Query Execution Request-Struktur im JSON-Format enthalten.

Um unsere Beispielanfrage zu senden, senden wir den folgenden JSON-Code:

{
"accountId": 2,
"sql": "SELECT SUM(completedamount) AS total, customerid FROM transaction GROUP BY customerid ORDER BY total DESC"
}

Die Anfrage wird innerhalb des Accounts mit der ID 2 (angegeben im Parameter accountId) ausgeführt. Die eigentliche SQL-Abfrage wird im Parameter sql bereitgestellt. Weitere Informationen finden Sie unter Zugriffskontrolle und Berechtigungen.

Die Antwort auf eine Übermittlungsanfrage ist eine Analytics Query Execution Response-Struktur im JSON-Format, die das queryToken der Ausführung enthält:

{
  "queryToken": "4d135f47-8c13-4b51-86ce-08c5d0f33a00"
}

3.3Status der Abfrageausführung überwachen

Eine übermittelte Abfrage wird asynchron verarbeitet. Die Abfrageausführung befindet sich zunächst im Status PROCESSING, und es sind keine Ergebnisse verfügbar. Sobald die Abfrageausführung verarbeitet und abgeschlossen ist, ändert sich der Status in SUCCESS, und die Abfrageergebnisse können abgerufen werden.

Schlägt die Abfrageausführung fehl oder wird sie vor Abschluss abgebrochen, ändert sich der Status in FAILED bzw. CANCELLED, und es werden keine Ergebnisse zurückgegeben.

Der aktuelle Status einer zuvor übermittelten Abfrage kann mit der API-Methode Query Execution Status (HTTP GET) überprüft werden. Dabei muss queryToken als URL-Pfadparameter festgelegt sein (verwenden Sie dazu das queryToken, das Sie beim ersten Aufruf von Abfrageausführung absenden erhalten haben).

Die Antwort auf den Aufruf der Methode Query Execution Status ist eine Submitted Query Execution-Struktur. In unserem Beispiel sieht die Anfrage-URL folgendermaßen aus:

/api/v2.0/analytics/queries/4d135f47-8c13-4b51-87ce-08c5d0f33a00

Sobald die Abfrageausführung den Status SUCCESS erreicht, wird eine Antwort ähnlich der folgenden empfangen:

{
"accountId": 2,
"createdTimestamp": "2025-03-21T07:56:56.110252Z",
"downloadRequests": 0,
"originalQuery": "SELECT SUM(completedAmount) AS total, customerId FROM transaction GROUP BY customerId ORDER BY total DESC",
"portalQueryToken": "4d135f47-8c13-4b51-87ce-08c5d0f33a00",
"resultFileBytes": 1476198,
"scannedBytes": 763075,
"status": "SUCCESS",
"totalBilledExecutionTimeMs": 1295
}
Note

Diese Anfrage (Query Execution Status) ist langanhaltend und hat eine maximale Zeitüberschreitung von ca. 100 Sekunden. Anfragen werden asynchron verarbeitet und können mehrere Minuten benötigen, um den endgültigen Status zu erreichen. Dies erfordert typischerweise lange Abfragen, die bis zu 100 Sekunden dauern können. Sollte die Anfrage nach dieser Zeit immer noch den Status PROCESSING aufweisen, wird empfohlen, den Aufruf später zu wiederholen. Bitte vermeiden Sie häufige Anfragen an diese API-Methode, da dies keinen Einfluss auf die Abfrageverarbeitung hat.

HTTP-Statuscodes:

  • 200 OK: Die Abfrage hat ihren endgültigen Status erreicht. Wird die Abfrage noch verarbeitet, wird der Status 200 mit dem Header Retry-After zurückgegeben.

  • 5xx: Interne Serverfehler.

3.4Abfrageausführung abbrechen

Eine Abfrageausführung im Status PROCESSING kann mit der Methode Cancel Query Execution (HTTP DELETE) abgebrochen werden. Fügen Sie das queryToken aus der Antwort Abfrageausführung absenden} ein.

Die Anfrage-URL sieht wie folgt aus:

/api/v2.0/analytics/queries/4d135f47-8c13-4b51-87ce-08c5d0f33a00

Beim Abbruch einer Abfrageausführung wird immer eine leere Antwort zurückgegeben, sofern kein Fehler vorliegt. Wenn die Abfrageausführung bereits einen endgültigen Status erreicht hat (SUCCESS, FAILED oder CANCELLED), wird der Abbruchversuch ignoriert.

3.5Abfrageausführungsergebnisse abrufen

Sobald Query Execution Status den Status SUCCESS zurückgibt, können die Abfrageausführungsergebnisse durch Aufruf der API-Methode Query Execution Result (HTTP GET-Anfrage) abgerufen werden.

Fügen Sie das queryToken aus der Antwort Abfrageausführung absenden ein.

Die Anfrage-URL sieht wie folgt aus:

api/v2.0/analytics/queries/4d135f47-8c13-4b51-86ce-08c5d0f33a00/result

Der Antworttext enthält eine temporäre Amazon S3-URL (gültig für ca. 5 Minuten), ähnlich der Folgendes:

https://...s3.eu-west-1.amazonaws.com/query-results/72aaf6a7-86eb-49bb-bded-5ef34e79385b.csv?X-Amz-Security-Token=[...]&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250321T082449Z&X-Amz-SignedHeaders=host&X-Amz-Credential=[...]&X-Amz-Expires=300&X-Amz-Signature=[...]
Note

Die Methode Query Execution Result generiert eine kurzlebige URL (gültig für 5 Minuten) für die Ergebnisdatei der Analytics-Abfrage. Jeder Download der Ausgabedatei ist kostenpflichtig, und wir zählen jede generierte Datei-URL als potenziellen Downloadversuch.

Bitte verwenden Sie diese API-Methode NICHT für regelmäßige Überprüfungen der Verfügbarkeit der Ergebnisdatei. Verwenden Sie stattdessen Query Execution Status für regelmäßige Überprüfungen.

HTTP-Statuscodes:

  • 200 OK: Die kurzlebige URL ist verfügbar.

  • 202 Akzeptiert: Das Ergebnis wird voraussichtlich später verfügbar sein.

  • 204 Kein Inhalt: Der Ergebnissatz ist leer (dies kann darauf hinweisen, dass die Abfrage abgebrochen wurde oder fehlgeschlagen ist).

  • 404 Nicht gefunden: Für das angegebene Token wurde keine Abfrage gefunden.

4Zugriffskontrolle und Berechtigungen

Die Verfügbarkeit von Tabellen und Daten wird durch Benutzerrollen geregelt, die von Ihrem Account Admin konfiguriert werden. Diese Rollen bestimmen, auf welche Daten Benutzer zugreifen und welche Aktionen sie durchführen können.

Beispiel:

  • Wenn ein Benutzer keinen Lesezugriff auf die Transaktionstabelle hat, wird diese nicht im Anlagenbereich angezeigt, und alle Abfragen , die darauf verweisen, schlagen fehl.

  • Ebenso führen Abfragen, die in Bereichen ausgeführt werden, die nicht mit dem Account des Benutzers verbunden sind, zu einem Erlaubnisfehler, da der Zugriff auf auf die Bereiche beschränkt ist, auf die der Benutzer Zugriff hat.

Wichtige Überlegungen:

  • Rollenbasierter Zugriff: Berechtigungen sind an Benutzerrollen gebunden, um Datensicherheit und Compliance zu gewährleisten.

  • Kontrolle auf Kontoebene: Kontoverwalter verwalten Rollenzuweisungen, um zu kontrollieren, wer auf bestimmte Tabellen, Ansichten oder Datensätze zugreifen kann.

Benötigen Sie Zugriffsänderungen?

Wenn Sie Zugriff auf zusätzliche Tabellen, Datasets oder Arbeitsbereiche benötigen, wenden Sie sich bitte an Ihren Account Manager. Er kann bei der Anpassung der Zugriffsrechte an Ihre Bedürfnisse unterstützen.