# Fonctionnement de l’API de rapports Accédez aux rapports financiers de Stripe de manière programmatique afin d'automatiser votre flux de rapprochement. > Grâce à Stripe Data Pipeline, vous pouvez désormais envoyer automatiquement vos données et rapports Stripe à Snowflake ou Amazon Redshift en quelques clics seulement. [En savoir plus](https://stripe.com/data-pipeline). Les [rapports financiers](https://dashboard.stripe.com/reports) dans le Dashboard fournissent des rapports téléchargeables au format CSV pour diverses tâches de comptabilité et de rapprochement. Ces rapports sont également disponibles via l’API, de sorte que vous pouvez les programmer afin qu’ils s’exécutent automatiquement, ou vous pouvez les exécuter chaque fois que vous avez besoin de recevoir les fichiers de rapport associés à des fins de comptabilité. ## Types de rapport Chaque rapport financier dans le Dashboard fournit plusieurs téléchargements CSV. Tous les téléchargements disponibles pour les rapports suivants sont également disponibles depuis l’API : - [Solde](https://docs.stripe.com/reports/report-types/balance.md) - [Rapprochement des virements](https://docs.stripe.com/reports/report-types/payout-reconciliation.md) - [Type de rapport sur les frais](https://docs.stripe.com/reports/report-types/fees.md) - [Taxes](https://docs.stripe.com/reports/report-types/tax.md) - [Plateformes Connect](https://docs.stripe.com/reports/report-types/connect.md) > #### Différences entre les formats monétaires utilisés dans les rapports CSV et ceux utilisés dans l'API > > Les rapports CSV formatent les montants monétaires en unités de devise *principale* en nombre décimal. Par exemple, 10 USD sont au format dollars et centimes (`10.00`). Cela diffère de l’API de Stripe, où vous spécifiez des montants dans l’unité *secondaire* de la devise (centimes de dollar américain) comme nombre entier. Dans l’API, 10 USD sont formatés en centimes (`1000`). ### Paramètres d’exécution Chaque rapport contient les paramètres obligatoires et facultatifs que vous fournissez lorsque vous créez une exécution de rapport. Prenez en compte les éléments suivants lorsque vous exécutez des rapports : - Pour presque tous les types de rapports, il est nécessaire de renseigner les paramètres d’exécution `interval_start` (inclusif) et `interval_end` (exclusif) sous la forme d’horodatages Unix. - Chaque ressource du type de rapport correspondante dispose des champs `data_available_start` et `data_available_end`. L’API renvoie une erreur de requête non valide (code d’état `400`) si votre exécution ne respecte pas les contraintes suivantes : - Les valeurs des paramètres `interval_start` et `interval_end` doivent être comprises entre `data_available_start` et `data_available_end` (inclus). - La valeur de `interval_start` doit être *antérieure* (et non égale à) `interval_end`. - Vous pouvez uniquement télécharger un rapport dans un fuseau horaire pour un `ReportType` avec un paramètre `timezone`. Pour ce faire, créez un objet `ReportRun` et indiquez le nom de votre choix au fuseau horaire de la base de données TZ. Le paramètre `timezone` est facultatif et est défini sur UTC s’il n’est pas fourni. Pour obtenir une liste des valeurs de fuseaux horaires valides, consultez la [base de données des fuseaux horaires IANA](https://www.iana.org/time-zones). - Les paramètres facultatifs `currency` et `report_category` filtrent les résultats pour n’afficher que les lignes correspondant aux valeurs indiquées. - Les rapports renvoient un ensemble de colonnes défini par défaut, mais la plupart des types de rapports vous permettent de personnaliser la sélection et l’ordre des colonnes présentées en incluant le paramètre facultatif `columns` avec une liste des noms de colonnes. ## Disponibilité des données Stripe prépare les données pour vos rapports deux fois par jour. Les [options de rapport](https://docs.stripe.com/reports/options.md#data-availability) donnent des détails concernant le temps de traitement et la disponibilité des données pour chaque rapport. Afin de déterminer par voie programmatique la plage horaire des données disponibles pour un type de rapport donné, [récupérez](https://docs.stripe.com/api.md#retrieve_reporting_report_type) l’objet `ReportType` qui vous intéresse. Par exemple, le rapport **Récapitulatif du solde** a l’ID `balance.summary.1`, vous pouvez donc récupérer l’objet comme suit : #### curl ```bash curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \ -u <>: ``` Dans l’exemple de réponse ci-dessous, les champs `data_available_start` et `data_available_end` reflètent l’ensemble des périodes valides pour ce type de rapport. Cependant, vous générerez le plus souvent des rapports avec un intervalle plus court durant cette période : ```json { "id": "balance.summary.1", "name": "Balance summary", "version": "1", "object": "reporting.report_type", "data_available_start": 1519862400, "data_available_end": 1517356800, "updated": 1517382720, } ``` Les horodatages, tels que `date_available_start`, sont exprimés en secondes écoulées depuis le début de l’ère Unix. Par exemple, `1519862400` représente l’horodatage `2018-03-01 00:00`. ### Notifications de nouvelles données Lorsqu’un type de rapport dispose de nouvelles données, Stripe publie un événement `reporting.report_type.updated` avec la mise à jour de l’objet `ReportType`. Pour accéder à ces événements, vous devez disposer d’un[webhook configuré](https://docs.stripe.com/webhooks.md#register-webhook) qui sélectionne explicitement de recevoir des événements `reporting.report_type.updated` ; les webhooks qui écoutent « tous les événements » ne les recevront pas. Pour réduire le trafic de webhook, Stripe n’envoie pas ces événements aux [endpoints webhook Connect](https://docs.stripe.com/connect/webhooks.md). Une fois que vous avez reçu l’événement, vous pouvez exécuter le rapport. Pour en savoir plus, consultez la section [ modèle d’intégration recommandé](https://docs.stripe.com/reports/api.md#integration-pattern). ## Créer et accéder aux exécutions de rapport L’objet API `ReportRun` représente une instance d’un `ReportType` généré avec des paramètres spécifiques. Consultez la documentation consacrée aux [types de rapports](https://docs.stripe.com/reports/api.md#report-types) pour obtenir la liste des paramètres obligatoires et facultatifs pour ce type. Par exemple, vous pouvez [créer](https://docs.stripe.com/api/reporting/report_run/create.md) le rapport **Récapitulatif de l’évolution du solde selon l’activité** pour le mois d’avril 2020 comme suit : #### 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. ``` Lorsqu’il est créé pour la première fois, l’objet apparaît avec `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 } ``` Lorsque la génération est terminée, Stripe met à jour l’objet qui prend le `status` `succeeded`. Il comporte également un objet imbriqué `result` contenant une URL que vous pouvez utiliser pour accéder au fichier avec votre clé API. Par exemple, si vous deviez [récupérer](https://docs.stripe.com/api/reporting/report_run/retrieve.md) le rapport ci-dessus une fois généré, la réponse serait : ```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" } } ``` Pour récupérer les contenus de fichier, utilisez votre clé API pour accéder au fichier spécifié par `result.url` : #### curl ```bash curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \ -u <>: ``` ### Notifications d’exécution de rapport La plupart des rapports sont générés en quelques minutes. Cependant, certaines générations peuvent être plus longues, selon la taille de votre ensemble de données et la période couverte par votre rapport. Lorsqu’une génération de rapport se termine, Stripe envoie l’un des deux webhooks : - Un webhook `reporting.report_run.succeeded` sera envoyé si la génération va à son terme. - Un webhook `reporting.report_run.failed` sera envoyé si la génération échoue. (Cela est rare, mais nous vous recommandons de préparer les intégrations pour gérer cette situation de la même façon que pour la détection d’une réponse `500`.) Dans les deux cas, la charge du webhook comprend l’objet `ReportRun` mis à jour, qui comprend respectivement l’état `succeeded` ou `failed`. > Les rapports que vous exécutez à partir du Dashboard ne déclenchent pas les événements webhook de reporting. ## Modèles d’intégration pour le reporting automatisé Configurez un webhook qui reçoit explicitement les événements `reporting.report_type.updated`. Les webhooks configurés pour écouter `all events` ne les recevront pas. > Si vous utilisez les[environnements de test](https://docs.stripe.com/sandboxes.md), vous ne recevrez pas les événements `reporting.report_type.updated`. 1. Un webhook `reporting.report_type.updated` est envoyé dès que les données d’une nouvelle journée sont disponibles pour un type de rapport donné. La charge utile comprend l’objet `ReportType` mis à jour. Vous recevez généralement 20 à 30 wekhooks chaque jour, deux pour chaque type de rapport. (Les utilisateurs différents sont éligibles pour des rapports différents.) 1. Après avoir reçu le webhook `reporting.report_type.updated` pour le type de rapport et la plage de disponibilité des données voulus, [créez une génération de rapport](https://docs.stripe.com/api/reporting/report_run/create.md). La réponse contient un nouvel objet `ReportRun`, initialisé avec l’état `status=pending`. 1. Lorsque la génération est terminée, un webhook `reporting.report_run.succeeded` est envoyé. Ce webhook comprend le champ imbriqué `result.url`. (Comme mentionné ci-dessus, dans les rares cas d’échecs nous envoyons plutôt un événement `reporting.report_run.failed`.) 1. Accédez aux contenus des fichiers via `result.url`, à l’aide de votre clé API. Stripe surveille les exécutions simultanées de rapports pour chaque compte. Afin de protéger notre infrastructure et d’assurer la qualité du service pour tous les utilisateurs, il se peut que nous limitions les demandes si un trop grand nombre de rapports sont exécutés simultanément. Si vous rencontrez une erreur de limite de débit (HTTP 429), attendez que certains de vos rapports en attente soient terminés avant d’en demander de nouveaux.