Générer un rapport depuis l'API

Les rapports financiers 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
• Rapprochement des virements
• Taxes
• Plateformes Connect

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. Consultez la base de données des fuseaux horaires IANA pour obtenir une liste des valeurs de fuseaux horaires valides.
• 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 donnent des détails concernant le temps de traitement et la disponibilité des données pour chaque rapport.

Afin de déterminer de façon programmatique la période de disponibilité des données pour un type de rapport donné, récupérez l’objet ReportType concerné. Par exemple, le rapport Récapitulatif du solde présente l’ID balance.summary.1 pour que vous puissiez récupérer les objets comme suit :

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

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 :

{
  "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

Dès qu’un type de rapport a de nouvelles données disponibles, Stripe publie un événement reporting.report_type.updated avec l’objet ReportType mis à jour. Pour accéder à ces événements, vous devez disposer d’un webhook configuré qui choisit explicitement de recevoir des événements reporting.report_type.updated ; les webhooks qui écoutent tous les événements (‘all events’) ne les reçoivent pas. Après avoir reçu un tel événement, vous pouvez générer le rapport. Pour plus de détails, consultez le modèle d’intégration recommandé.

Création et accès aux 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 pour obtenir la liste des paramètres obligatoires et facultatifs pour ce type. Par exemple, vous pouvez créer le rapport Récapitulatif de l’évolution du solde selon l’activité pour le mois d’avril 2020 comme suit :

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.

Lorsqu’il est créé pour la première fois, l’objet apparaît avec 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
}

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 le rapport ci-dessus une fois généré, la réponse serait :

{
  "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 https://files.stripe.com/v1/files/file_xs8vrJzC/contents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Notification de fin de génération du 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.

Modèle d’intégration recommandé pour le reporting automatisé

Configurez un webhook qui choisit explicitement de recevoir des événements reporting.report_type.updated ; les webhooks qui écoutent « tous les événements » ne vont pas les recevoir.

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.)
2. 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. La réponse contient un nouvel objet ReportRun, initialisé avec l’état status=pending.
3. 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.)
4. Accédez aux contenus des fichiers via result.url, à l’aide de votre clé API.