Ejecutar un informe desde la API
Nota
You can now automatically send your Stripe data and reports to Snowflake or Amazon Redshift in a few clicks with Stripe Data Pipeline. Learn more.
Los informes financieros del Dashboard pueden descargarse en formato CSV para diferentes actividades de conciliación y contabilidad. Estos informes también están disponibles a través de la API, así que puedes programarlos para que se ejecuten automáticamente o ejecutarlos cuando tengas que recibir los archivos de informes asociados para fines contables.
Tipos de informes
Cada informe financiero del Dashboard puede descargarse en formato CSV de diferentes maneras. Todos las descargas disponibles de los siguientes informes también están disponibles desde la API:
Los formatos monetarios en informes CSV y de la API son diferentes
Los informes en CSV formatean los importes monetarios en las unidades de moneda más grandes como números con decimales. Por ejemplo, el CSV formatea USD 10 en dólares estadounidenses con centavos (10.00
). Esto difiere de la API de Stripe, en la cual los importes se especifican en la unidad menor de la moneda (centavos estadounidenses) como número entero. En la API, formatearás USD 10 como centavos (1000
).
Parámetros de ejecución
Cada informe tiene parámetros obligatorios y opcionales que debes especificar para crear la ejecución del informe. Al ejecutar los informes, ten en cuenta lo siguiente:
- Para casi todos los tipos de informes, es necesario especificar los parámetros de ejecución
interval_start
(inclusive) einterval_end
(sin incluir) como marcas de tiempo de Unix. - Cada recurso de tipo de informe correspondiente tiene los campos
data_available_start
ydata_available_end
. La API devuelve un error por solicitud no válida (código de estado400
) si la ejecución no cumple con las siguientes restricciones:- Los valores
interval_start
einterval_end
deben estar entredata_available_start
ydata_available_end
(inclusive). - El valor
interval_start
debe ser anterior al valorinterval_end
. Dichos valores no pueden ser iguales.
- Los valores
- Solo puedes descargar un informe en una zona horaria para un
ReportType
con un parámetrotimezone
. Para ello, crea un objetoReportRun
y proporciona el nombre de la zona horaria deseada de la base de datos de zonas horarias. Si no se especifica otra cosa, el parámetrotimezone
es opcional, y la configuración predeterminada será UTC. Para obtener una lista de valores de zona horaria válidos, consulta la Base de datos de zonas horarias de la IANA. - Los parámetros opcionales
currency
yreport_category
sirven para filtrar los resultados y obtener solo las filas que coincidan con los valores proporcionados. - De manera predeterminada, los informes devuelven un conjunto de columnas. En la mayoría de los tipos de informes, puedes personalizar la selección y el orden de las columnas que se obtendrán. Para ello, tienes que incluir el parámetro opcional
columns
con una lista de nombres de columnas.
Disponibilidad de datos
Stripe prepara los datos para tus informes casi a diario. Las Opciones de informes dan detalles sobre los tiempos de procesamiento previstos y la disponibilidad de datos para cada informe.
Para establecer mediante programación el intervalo de tiempo durante el cual los datos estarán disponibles para un determinado tipo de informe, recupera el objeto ReportType
de tu interés. Por ejemplo, el informe Resumen de saldo tiene el ID balance.summary.1
, por lo tanto puedes recuperar el objeto de la siguiente manera:
En la respuesta de ejemplo que aparece a continuación, los campos data_available_start
y data_available_end
reflejan el intervalo completo de períodos válidos para este tipo de informe. Sin embargo, muchas veces ejecutarás informes por un intervalo menor dentro de ese período:
{ "id": "balance.summary.1", "name": "Balance summary", "version": "1", "object": "reporting.report_type", "data_available_start": 1519862400, "data_available_end": 1517356800, "updated": 1517382720, }
Las marcas de tiempo, como date_available_start
, se miden en segundos desde la época de Unix. Por ejemplo, 1519862400
representa la marca de tiempo 2018-03-01 00:00
.
Notificaciones sobre nuevos datos
Tan pronto como un tipo de informe tiene nuevos datos disponibles, Stripe publica un evento reporting.report_type.updated
con el objeto ReportType
actualizado. Para acceder a estos eventos, debes tener configurado un webhook que opte expresamente por recibir eventos reporting.report_type.updated
, ya que los webhooks que escuchen ‘all events’ no los recibirán. Después de recibir dicho evento, puedes ejecutar el informe. Para obtener más detalles, consulta el patrón de integración recomendado.
Cómo crear ejecuciones de informes y cómo acceder a ellas
El objeto ReportRun
de la API representa una instancia de un ReportType
generado con parámetros específicos. Revisa la documentación sobre los tipos de informes para ver la lista de parámetros obligatorios y opcionales de ese tipo en particular. Por ejemplo, puedes crear un informe de Resumen de cambios de saldos conforme a la actividad para abril de 2020 de la siguiente manera:
Cuando se crea por primera vez, el objeto aparece con 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 }
Cuando se completa la ejecución, Stripe actualiza el objeto y su status
pasa a succeeded
. También tiene un objeto result
anidado que contiene una dirección URL que podrás usar para acceder al archivo con tu clave de API. Por ejemplo, si tuvieras que recuperar la ejecución del informe que aparece más arriba después de que haya finalizado, la respuesta será la siguiente:
{ "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" } }
Para recuperar el contenido del archivo, usa la clave de API para acceder al archivo especificado por result.url
:
Notificación de finalización de la ejecución del informe
La mayoría de las ejecuciones se completan en cuestión de minutos. Sin embargo, algunas ejecuciones pueden tardar más según el tamaño total de los datos definidos y el intervalo de tiempo que cubra tu informe.
Cuando finaliza la ejecución de un informe solicitado, Stripe envía uno de estos dos webhooks:
- Se enviará el webhook
reporting.report_run.succeeded
si la ejecución se completa con éxito. - Se enviará el webhook
reporting.report_run.failed
si la ejecución falla. (Es raro que esto ocurra, pero te recomendamos tener preparada tu integración para manejar este caso de la misma manera que para la detección de una respuesta500
).
En ambos casos, la carga del webhook incluye el objeto ReportRun
actualizado, que incluye el estado succeeded
o failed
, respectivamente.
Modelo de integración recomendado para informes automáticos
Configura un webhook que opte expresamente por recibir eventos reporting.report_type.updated
; no serán recibidos por los webhooks que escuchen «todos los eventos».
- El webhook
reporting.report_type.updated
se envía cuando los datos del nuevo día están disponibles para un determinado tipo de informe. La carga incluye el objetoReportType
actualizado. En general, recibirás entre 20 y 30 webhooks por día, dos por cada tipo de informe. (Los diferentes usuarios tienen acceso a diferentes informes). - Al recibir el webhook
reporting.report_type.updated
para el tipo de informe y el rango de datos disponibles deseados, crea la ejecución del informe. La respuesta contiene un nuevo objetoReportRun
que se inicializa constatus=pending
. - Cuando se completa la ejecución, se envía un webhook
reporting.report_run.succeeded
. Este webhook incluye el camporesult.url
anidado. (Como se menciona más arriba, en el improbable caso de que falle, se enviará un eventoreporting.report_run.failed
). - Accede al contenido del archivo en
result.url
usando tu clave de API.