# Cómo funciona la API Reports Accede a informes financieros de Stripe mediante programación para automatizar tu flujo de trabajo de conciliación. > Con Stripe Data Pipeline, ahora puedes enviar tus datos e informes de Stripe de forma automática a Snowflake o Amazon Redshift con solo unos clicks. [Obtén más información](https://stripe.com/data-pipeline). Los [informes financieros](https://dashboard.stripe.com/reports) 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: - [Saldo](https://docs.stripe.com/reports/report-types/balance.md) - [Conciliación de transferencias](https://docs.stripe.com/reports/report-types/payout-reconciliation.md) - [Tipo de informe de comisiones](https://docs.stripe.com/reports/report-types/fees.md) - [Impuesto](https://docs.stripe.com/reports/report-types/tax.md) - [Plataformas Connect](https://docs.stripe.com/reports/report-types/connect.md) > #### 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) e `interval_end` (sin incluir) como marcas de tiempo de Unix. - Cada recurso de tipo de informe correspondiente tiene los campos `data_available_start` y `data_available_end`. La API devuelve un error por solicitud no válida (código de estado `400`) si la ejecución no cumple con las siguientes restricciones: - Los valores `interval_start` e `interval_end` deben estar entre `data_available_start` y `data_available_end` (inclusive). - El valor `interval_start` debe ser *anterior* al valor `interval_end`. Dichos valores no pueden ser iguales. - Solo puedes descargar un informe en una zona horaria para un `ReportType` con un parámetro `timezone`. Para ello, crea un objeto `ReportRun` 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ámetro `timezone` 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](https://www.iana.org/time-zones). - Los parámetros opcionales `currency` y `report_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](https://docs.stripe.com/reports/options.md#data-availability) 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](https://docs.stripe.com/api.md#retrieve_reporting_report_type) 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: #### curl ```bash curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \ -u <>: ``` 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: ```json { "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 Cuando hay nuevos datos disponibles para un tipo de informe, Stripe publica un evento `reporting.report_type.updated` con el objeto `ReportType` actualizado. Para acceder a estos eventos, debes tener un [webhook configurado](https://docs.stripe.com/webhooks.md#register-webhook) que seleccione explícitamente recibir eventos `reporting.report_type.updated`; los webhooks que escuchen «todos los eventos» no los recibirán. Para reducir el tráfico de webhooks, Stripe no envía estos eventos a los [puntos de conexión de webhooks de Connect](https://docs.stripe.com/connect/webhooks.md). Después de recibir el evento, puedes ejecutar el informe. Para obtener más detalles, consulta el [patrón de integración recomendado](https://docs.stripe.com/reports/api.md#integration-pattern). ## Crea y accede a ejecuciones de informes 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](https://docs.stripe.com/reports/api.md#report-types) para ver la lista de parámetros obligatorios y opcionales de ese tipo en particular. Por ejemplo, puedes [crear](https://docs.stripe.com/api/reporting/report_run/create.md) un informe de **Resumen de cambios de saldos conforme a la actividad** para abril de 2020 de la siguiente manera: #### 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. ``` Cuando se crea por primera vez, el objeto aparece con `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 } ``` 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](https://docs.stripe.com/api/reporting/report_run/retrieve.md) la ejecución del informe que aparece más arriba después de que haya finalizado, la respuesta será la siguiente: ```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" } } ``` Para recuperar el contenido del archivo, usa la clave de API para acceder al archivo especificado por `result.url`: #### curl ```bash curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \ -u <>: ``` ### Notificaciones de ejecución de informes 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 respuesta `500`). En ambos casos, la carga del webhook incluye el objeto `ReportRun` actualizado, que incluye el estado `succeeded` o `failed`, respectivamente. > Los informes que ejecutas desde el Dashboard no activan los eventos de webhook. ## Patrones de integración automatizada de informes Configura un webhook que opte expresamente por recibir eventos `reporting.report_type.updated`. Los webhooks que escuchen `todos los eventos` no los recibirán. > Si usas [sandboxes](https://docs.stripe.com/sandboxes.md), no recibirás eventos `reporting.report_type.updated`. 1. 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 objeto `ReportType` 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). 1. 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](https://docs.stripe.com/api/reporting/report_run/create.md). La respuesta contiene un nuevo objeto `ReportRun` que se inicializa con `status=pending`. 1. Cuando se completa la ejecución, se envía un webhook `reporting.report_run.succeeded`. Este webhook incluye el campo `result.url` anidado. (Como se menciona más arriba, en el improbable caso de que falle, se enviará un evento `reporting.report_run.failed`). 1. Accede al contenido del archivo en `result.url` usando tu clave de API. Stripe supervisa las ejecuciones concurrentes de informes para cada cuenta. Para proteger nuestra infraestructura y garantizar la calidad del servicio para todos los usuarios, podríamos regular las solicitudes si se ejecutan demasiados informes de forma simultánea. Si te encuentras con un error de límite de frecuencia (HTTP 429), espera a que finalicen algunas de las ejecuciones de informes pendientes antes de solicitar otras nuevas.