Bericht über die API erstellen

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:

• Guthaben
• Auszahlungsabgleich
• Tax
• Connect-Plattformen

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).
• Sie können Berichte in einer Zeitzone nur für einen ReportType mit dem Parameter timezone herunterladen. Erstellen Sie dazu ein ReportRun-Objekt und geben Sie die gewünschte Zeitzonenbezeichnung in der Zeitzonendatenbank an. Der Parameter timezone ist optional und hat den Standardwert UTC, falls nichts anderes angegeben wird. Eine Liste der gültigen Zeitzonenwerte finden Sie in der Zeitzonendatenbank der IANA.
• 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.

Um den Zeitraum für die Verfügbarkeit der Daten für eine bestimmte Berichtsart programmgesteuert festzulegen, rufen Sie das entsprechende ReportType-Objekt ab. Der Bericht Saldenübersicht hat zum Beispiel die ID balance.summary.1, weshalb Sie das Objekt wie folgt abrufen können:

curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

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

Sobald für eine Berichtsart neue Daten verfügbar sind, veröffentlicht Stripe das Ereignis reporting.report_type.updated mit dem aktualisierten Objekt ReportType. Sie müssen einen Webhook konfigurieren, der ausdrücklich den Empfang von reporting.report_type.updated-Ereignissen unterstützt, um auf diese Ereignisse zugreifen zu können. Webhooks, die auf „alle Ereignisse“ warten, können diese Ereignisse nicht empfangen. Nachdem Sie ein entsprechendes Ereignis empfangen haben, können Sie anschließend den Bericht erstellen. Weitere Informationen finden Sie im empfohlenen Integrationsmuster.

Berichtsausführungen erstellen und aufrufen

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:

curl https://api.stripe.com/v1/reporting/report_runs \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "report_type"="balance_change_from_activity.itemized.3" \
  -d "parameters[interval_start]"=1577865600 \
  -d "parameters[interval_end]"=1580544000 \
  -d "parameters[timezone]"="America/Los_Angeles" \
  -d "parameters[columns][]"="created" \
  -d "parameters[columns][]"="reporting_category" \
  -d "parameters[columns][]"="net"

# Timestamps are for 2020-01-01 00:00 PST and 2020-02-01 00:00 PST.
# The columns parameter is optional. A default set of columns will be provided if you don't specify a value.
# Note that a live-mode API key is required.

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:

curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Benachrichtigung über Abschluss der Berichtsausführung

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.

Empfohlenes Integrationsmuster für automatisierte Berichterstellung

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

1. 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.)
2. 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.
3. 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.)
4. Greifen Sie mit Ihrem API-Schlüssel auf den Dateiinhalt unter result.url zu.