Funktionsweise der Reports API

Greifen Sie programmgesteuert auf die Finanzberichte von Stripe zu, um Ihre Abläufe für Abgleiche zu automatisieren.

Hinweis

Mit der Stripe Data Pipeline können Sie jetzt Ihre Stripe-Daten und -Berichte mit wenigen Klicks automatisch an Snowflake oder Amazon Redshift senden. Mehr erfahren.

Die Finanzberichte im Dashboard umfassen Berichte, die als CSV-Dateien für verschiedene Aufgaben rund um Buchhaltung und Abgleich heruntergeladen werden können. Diese Berichte sind zudem über die API verfügbar, d. h. Sie können ihre automatische Ausführung planen oder sie immer dann ausführen, wenn Sie die zugehörigen Berichtsdateien für Buchhaltungszwecke benötigen.

Berichtsarten

Jeder Finanzbericht im Dashboard umfasst mehrere Berichte, die als CSV-Dateien heruntergeladen werden können. Alle verfügbaren Downloads für die folgenden Berichte sind auch über die API abrufbar:

Die CSV- und API-Formate bezüglich der Geldbeträge unterscheiden sich

Die CSV-Berichte stellen Geldbeträge in der größeren Währungseinheit als Dezimalzahl dar. Zum Beispiel werden 10 USD als Dollar und Cent (10.00) formatiert. Das unterscheidet sich von der Stripe API, in der die Beträge in der kleineren Währungseinheit (US-Cent) als Ganzzahl angegeben werden. In der API werden 10 USD als Cent (1000) formatiert.

Parameter ausführen

Jeder Bericht enthält erforderliche und optionale Parameter, die Sie beim Erstellen einer Berichtsausführung angeben. Beachten Sie beim Erstellen von Berichten Folgendes:

Für nahezu alle Berichtsarten müssen Sie die Ausführungsparameter interval_start (inklusive) und interval_end (exklusive) als Unix-Zeitstempel angeben.
Jede Ressource der jeweiligen Berichtsart verfügt über die Felder data_available_start und data_available_end. Die API gibt den Fehler „Ungültige Anfrage“ (Statuscode 400) zurück, wenn Ihre Ausführung die folgenden Einschränkungen nicht erfüllt:
- Die Werte interval_start und interval_end müssen zwischen data_available_start und (einschließlich) data_available_end liegen.
- Der Wert interval_start muss vor interval_end liegen (und darf nicht den gleichen Wert haben).
You can only download a report in a time zone for a ReportType with a timezone parameter. To do so, create a ReportRun object and supply the desired TZ database time zone name. The timezone parameter is optional and defaults to UTC if not supplied. See IANA Time Zone Database for a list of valid timezone values.
Mit den optionalen Parametern currency und report_category lassen sich die Ergebnisse so filtern, dass nur Zeilen angezeigt werden, die den angegebenen Werten entsprechen.
Berichte geben Standardspalten zurück. Für die meisten Berichtsarten können Sie die Auswahl und Sortierung der Spalten im Berichtsergebnis jedoch anpassen, indem Sie den optionalen Parameter columns mit einer Liste von Spaltenbezeichnungen mit angeben.

Verfügbarkeit der Daten

Stripe erstellt die Daten für Ihre Berichte zweimal täglich. Unter Berichtsoptionen finden Sie Informationen zur erwarteten Bearbeitungszeit und zur Datenverfügbarkeit für den jeweiligen Bericht.

To programmatically determine the time range of data available for a given report type, retrieve the ReportType object of interest. For example, the Balance summary report has the ID balance.summary.1, so you can retrieve the object as follows:

In der nachfolgenden Beispielantwort zeigen die Felder data_available_start und data_available_end den gesamten Zeitraum, in dem diese Berichtsart gültig ist. Allerdings werden die Berichte häufiger für einen kürzeren Zeitabschnitt innerhalb dieses Zeitraums erstellt:

{
  "id": "balance.summary.1",
  "name": "Balance summary",
  "version": "1",
  "object": "reporting.report_type",
  "data_available_start": 1519862400,
  "data_available_end": 1517356800,
  "updated": 1517382720,
}

Zeitstempel, wie zum Beispiel date_available_start, werden seit der Unix-Epoche in Sekunden gemessen. Beispielsweise steht 1519862400 für den Zeitstempel 2018-03-01 00:00.

Benachrichtigung über die Verfügbarkeit neuer Daten

Wenn für einen Berichtstyp neue Daten verfügbar sind, veröffentlicht Stripe das Ereignis reporting.report_type.updated mit dem aktualisierten ReportType-Objekt. Um auf diese Ereignisse zuzugreifen, müssen Sie einen Webhook konfiguriert haben, der explizit auswählt, ob reporting.report_type.updated-Ereignisse empfangen werden sollen. Webhooks, die auf „alle Ereignisse“ achten, erhalten diese nicht.

Um den Webhook-Datenverkehr zu reduzieren, sendet Stripe diese Ereignisse nicht an Connect-Webhook-Endpoints. Nachdem Sie das Ereignis empfangen haben, können Sie den Bericht erstellen. Weitere Informationen finden Sie unter dem empfohlenen Integrationsmuster.

Berichtsläufe erstellen und abrufen

Das API-Objekt ReportRun stellt eine Instanz eines ReportType dar, der mit bestimmten Parametern generiert wurde. Sehen Sie sich die Dokumentation für den Berichtstyp an, um eine Liste der erforderlichen und optionalen Parameter für diesen Typ zu erhalten. Beispielsweise können Sie den Bericht Guthabenänderung resultierend aus Aktivitäten für April 2020 wie folgt erstellen:

Wenn das Objekt erstellt wird, erscheint es zunächst mit status="pending":

{
  "id": "frr_123",
  "object": "reporting.report_run",
  "livemode": true,
  "report_type": "balance_change_from_activity.itemized.3",
  "parameters": {
    "columns": [ "created", "reporting_category", "net" ],
    "interval_start": 1577865600,
    "interval_end": 1580544000,
    "timezone": "America/Los_Angeles"
  },
  "created": 1580832900,
  "status": "pending",
  "result": null
}

Nach der Erstellung des Berichts aktualisiert Stripe das Objekt, sodass es den status succeeded hat. Es hat außerdem ein verschachteltes result-Objekt, das eine URL für den Zugriff auf die Datei mit Ihrem API-Schlüssel enthält. Wenn Sie zum Beispiel die oben genannte Berichtsausführung nach deren Abschluss abrufen, erhalten Sie folgende Antwort:

{
  "id": "frr_123",
  "object": "reporting.report_run",
  "livemode": true,
  "report_type": "balance_change_from_activity.itemized.3",
  "parameters": {
    "columns": [ "created", "reporting_category", "net" ],
    "interval_start": 1577865600,
    "interval_end": 1580544000,
    "timezone": "America/Los_Angeles"
  },
  "created": 1580832900,
  "status": "succeeded",
  "succeeded_at": 1580832960,
  "result": {
    "id": "file_xs8vrJzC",
    "object": "file",
    "url": "https://files.stripe.com/v1/files/file_xs8vrJzC/contents",
    "created": 1580832960,
    "purpose": "report_run",
    "size": 53075,
    "type": "csv"
  }
}

Verwenden Sie zum Abrufen des Dateiinhalts Ihren API-Schlüssel, um auf die durch result.url angegebene Datei zuzugreifen:

Benachrichtigungen über Berichtsausführungen

Die meisten Ausführungen sind innerhalb weniger Minuten abgeschlossen. Allerdings können einige Ausführungen je nach Größe des Datensatzes und dem vom Bericht abgedeckten Zeitraum länger dauern.

Sobald eine angeforderte Berichterstellung abgeschlossen ist, übermittelt Stripe einen von zwei Webhooks:

Der Webhook reporting.report_run.succeeded wird übermittelt, wenn die Ausführung erfolgreich abgeschlossen wurde.
Der Webhook reporting.report_run.failed wird übermittelt, wenn die Ausführung fehlschlägt. (Dies sollte selten vorkommen, aber wir empfehlen, die Integrationen für diesen Fall genauso vorzubereiten wie für eine Antwort 500.)

In beiden Fällen enthält die Webhook-Nutzlast das aktualisierte Objekt ReportRun mit dem Status succeeded bzw. failed.

Häufiger Fehler

Berichte, die Sie über das Dashboard ausführen, lösen die Webhook-Ereignisse für die Berichterstattung nicht aus.

Automatisierte Integrationsmuster für Berichte

Konfigurieren Sie einen Webhook, der ausdrücklich den Empfang von reporting.report_type.updated-Ereignissen auswählt. Webhooks, die auf alle Ereignisse warten, erhalten diese Ereignisse nicht.

Hinweis

Wenn Sie Sandboxes verwenden, erhalten Sie keine reporting.report_type.updated-Ereignisse…

Der Webhook reporting.report_type.updated wird gesendet, sobald neue Daten für eine bestimmte Berichtsart verfügbar sind. Die Nutzlast enthält das aktualisierte Objekt ReportType. In der Regel erhalten Sie 20 bis 30 Webhooks pro Tag, und zwar einen für jede Berichtsart. (Für unterschiedliche Nutzer/innen sind verschiedene Berichte möglich.)
Erstellen Sie eine Berichtsausführung, nachdem Sie den Webhook reporting.report_type.updated für die gewünschte Berichtsart und den Bereich der Datenverfügbarkeit empfangen haben. Die Antwort enthält ein neues ReportRun-Objektund wird mitstatus=pending` initialisiert.
Wenn ein Bericht erstellt wurde, wird der Webhook reporting.report_run.succeeded übermittelt. Dieser Webhook enthält das verschachtelte Feld result.url. (Wie oben erwähnt, wird im seltenen Fehlerfall stattdessen das Ereignis reporting.report_run.failed übermittelt.)
Greifen Sie mit Ihrem API-Schlüssel auf den Dateiinhalt unter result.url zu.

Stripe überwacht die gleichzeitige Ausführung von Berichten für jedes Konto. Um unsere Infrastruktur zu schützen und die Servicequalität für alle Nutzer/innen zu gewährleisten, können wir Anfragen drosseln, wenn zu viele Berichte gleichzeitig ausgeführt werden. Wenn ein Fehler wegen einer Ratenbegrenzung (HTTP 429) auftritt, warten Sie, bis einige der ausstehenden Berichtsausführungen abgeschlossen sind, bevor Sie neue Berichte anfordern.