# Funktionsweise der Reports API Greifen Sie programmgesteuert auf die Finanzberichte von Stripe zu, um Ihre Abläufe für Abgleiche zu automatisieren. > 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](https://stripe.com/data-pipeline). Die [Finanzberichte](https://dashboard.stripe.com/reports) 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](https://docs.stripe.com/reports/report-types/balance.md) - [Auszahlungsabgleich](https://docs.stripe.com/reports/report-types/payout-reconciliation.md) - [Gebührenberichtstyp](https://docs.stripe.com/reports/report-types/fees.md) - [Tax](https://docs.stripe.com/reports/report-types/tax.md) - [Connect-Plattformen](https://docs.stripe.com/reports/report-types/connect.md) > #### 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). - 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 IANA](https://www.iana.org/time-zones). - 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](https://docs.stripe.com/reports/options.md#data-availability) 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](https://docs.stripe.com/api.md#retrieve_reporting_report_type) 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 ```bash curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \ -u <>: ``` 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: ```json { "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](https://docs.stripe.com/webhooks.md#register-webhook) 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](https://docs.stripe.com/connect/webhooks.md). Nachdem Sie das Ereignis empfangen haben, können Sie den Bericht erstellen. Weitere Informationen finden Sie unter dem [empfohlenen Integrationsmuster](https://docs.stripe.com/reports/api.md#integration-pattern). ## 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](https://docs.stripe.com/reports/api.md#report-types) 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](https://docs.stripe.com/api/reporting/report_run/create.md): #### curl ```bash curl https://api.stripe.com/v1/reporting/report_runs \ -u <>: \ -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"`: ```json { "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](https://docs.stripe.com/api/reporting/report_run/retrieve.md), erhalten Sie folgende Antwort: ```json { "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 ```bash curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \ -u <>: ``` ### 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`. > 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. > Wenn Sie [Sandboxes](https://docs.stripe.com/sandboxes.md) verwenden, erhalten Sie keine `reporting.report_type.updated`-Ereignisse… 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.) 1. [Erstellen Sie eine Berichtsausführung](https://docs.stripe.com/api/reporting/report_run/create.md), 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`-Objekt`und wird mit`status=pending` initialisiert. 1. 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.) 1. 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.