Cómo funciona la API Reports

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:

• Saldo
• Conciliación de transferencias
• Tipo de informe de comisiones
• Impuesto
• Plataformas Connect

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.
• 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 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:

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

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

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 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. Después de recibir el evento, puedes ejecutar el informe. Para obtener más detalles, consulta el patrón de integración recomendado.

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 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:

curl https://api.stripe.com/v1/reporting/report_runs \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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":

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

curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

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.

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.

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).

2. 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 objeto ReportRun que se inicializa con status=pending.

3. 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).

4. 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.