Carga datos de Stripe en BigQuery

Puedes cargar datos de Stripe a BigQuery con el conector de Stripe con el Servicio de transferencia de datos de BigQuery. Con el conector de Stripe, puedes programar trabajos de transferencia recurrentes que agreguen tus datos más recientes de Stripe a BigQuery.

Limitaciones

Las transferencias de datos de Stripe están sujetas a las siguientes limitaciones:

  • Una transferencia de datos de Stripe carga las monedas según las unidades menores de Stripe. Para obtener más información, consulta Unidades menores en los importes de la API.
  • El conector de Stripe solo transfiere informes generados previamente para cada cuenta de Stripe. El conector de Stripe no genera informes nuevos basados en datos nuevos de Stripe.
    • Para transferir informes actualizados, genéralos manualmente en el panel de Stripe antes de iniciar la transferencia de datos de Stripe.
    • Para obtener más información, consulta Informes de Stripe.
  • El conector de Stripe no admite eventos basados en webhooks, actualizaciones en tiempo real ni Stripe Sigma.
  • Las transferencias de datos de Stripe desde regiones de Stripe que están en versión preliminar pueden tener problemas con las transferencias de datos:
    • Las opciones de filtrado están restringidas o no están disponibles en las regiones de versión preliminar de Stripe.
    • Las transferencias de datos y las consultas condicionales no se admiten en las regiones de versión preliminar de Stripe.
    • Es posible que encuentres tiempos de ejecución de transferencia de datos prolongados cuando transfieras datos desde regiones de versión preliminar de Stripe.
  • El conector de Stripe admite algunos objetos con el filtro StartDate.
    • El formato obligatorio para el filtro StartDate es YYYY-MM-DD. Si no se proporciona una fecha de inicio, el conector se establece de forma predeterminada en tres años antes de la fecha actual. Si se proporciona una fecha anterior al 1 de enero de 2011, el conector usará automáticamente el 1 de enero de 2011.
    • Para obtener una lista de los objetos compatibles, consulta Objetos con compatibilidad con el filtro StartDate.
  • Una sola configuración de transferencia solo puede admitir una ejecución de transferencia de datos en un momento determinado. Si se programa una segunda transferencia de datos para que se ejecute antes de que se complete la primera, solo se completará la primera transferencia de datos, mientras que se omitirán las demás transferencias de datos que se superpongan con la primera.
    • Para evitar que se omitan transferencias dentro de una sola configuración de transferencia, te recomendamos que aumentes la duración del tiempo entre las transferencias de datos grandes configurando la Frecuencia de repetición.
  • Si tu adjunto de red se creó en un proyecto de Google Cloud que es diferente del proyecto de Google Cloud de la transferencia de datos, debes otorgar los permisos compute.networkAttachments.get y compute.networkAttachments.update al agente de servicio que pertenece al proyecto de Google Cloud en el que se creó la transferencia de datos.

Antes de comenzar

En las siguientes secciones, se describen los pasos que debes seguir antes de crear una transferencia de datos de Stripe.

Requisitos previos de Stripe

  • Debes tener una cuenta de desarrollador de Stripe para autorizar una transferencia de datos de Stripe. Para registrar una cuenta de Stripe, consulta Registro de Stripe.
  • Configura tu aplicación de la plataforma de Stripe con los siguientes pasos:
    1. Navega a la sección Developers en el panel de Stripe.
    2. En Connect, configura tu plataforma para que admita cuentas Standard y Express.
  • Para crear una transferencia de datos de Stripe, se necesita la siguiente información:
    • Anota el ID de tu cuenta de Stripe. Para obtener más información, consulta Crea una cuenta.
    • Anota tu clave secreta o restringida. Para obtener más información, consulta Claves de API.
  • Si planeas transferir datos de cuentas conectadas, asegúrate de que tu plataforma esté configurada para Stripe Connect y tenga acceso a las funciones de cuenta necesarias. Para obtener más información sobre Stripe Connect, consulta Plataformas y mercados con Stripe Connect.

Roles de BigQuery requeridos

Para obtener los permisos que necesitas para crear una transferencia, pídele a tu administrador que te otorgue el rol de IAM de administrador de BigQuery (roles/bigquery.admin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear una transferencia. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear una transferencia:

  • bigquery.transfers.update en el usuario
  • bigquery.datasets.get en el conjunto de datos de destino
  • bigquery.datasets.update en el conjunto de datos de destino

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Requisitos previos de BigQuery

Tipos de cuentas de Stripe

El conector de Stripe admite cuentas de la plataforma de Stripe y cuentas conectadas de Stripe. Para obtener más información, consulta Tipos de cuentas de Connect.

Cómo conectarse a cuentas de plataformas

Para ejecutar una transferencia de datos de Stripe desde una sola cuenta de plataforma, haz lo siguiente cuando establezcas la configuración de transferencia:

  • Ingresa el ID de la cuenta de plataforma en el campo ID de cuenta.
  • Ingresa el secreto o la clave restringida de la cuenta de la plataforma en el campo Secreto/clave de API.
  • En SyncAllConnectedAccounts, selecciona Falso.

Para ejecutar una transferencia de datos de Stripe para varias cuentas, por ejemplo, para una cuenta de plataforma vinculada con cuentas conectadas, haz lo siguiente cuando establezcas la configuración de transferencia:

  • Ingresa el ID de la cuenta de plataforma en el campo ID de cuenta.
  • Ingresa el secreto o la clave restringida de la cuenta de la plataforma en el campo Secreto/clave de API.
  • En SyncAllConnectedAccounts, selecciona Verdadero.

Conectarse a cuentas conectadas

Las cuentas conectadas son cuentas de Stripe vinculadas a Stripe con Stripe Connect.

Para ejecutar una transferencia de datos de Stripe desde una cuenta conectada, haz lo siguiente cuando establezcas la configuración de transferencia:

  • Ingresa el ID de la cuenta de plataforma para la cuenta conectada en el campo ID de cuenta.
  • Ingresa la clave secreta o restringida de la cuenta de plataforma a la que está conectada la cuenta conectada en el campo Clave de API/secreta.
  • En SyncAllConnectedAccounts, selecciona Falso.

Configura una transferencia de datos de Stripe

Agrega datos de Stripe a BigQuery configurando una configuración de transferencia con una de las siguientes opciones:

Console

  1. Ve a la página Transferencia de datos en la consola de Google Cloud .

    Ir a Transferencias de datos

  2. Haz clic en Crear transferencia.

  3. En la sección Tipo de fuente, en Fuente, selecciona Stripe.

  4. En la sección Detalles de fuente de datos, haz lo siguiente:

    • En ID de cuenta conectada o de plataforma, ingresa el ID de la cuenta de Stripe. Para obtener más información, consulta Requisitos previos de Stripe.
    • En Clave secreta de Stripe, ingresa la clave de API de la cuenta de Stripe. Para obtener más información, consulta los requisitos previos de Stripe.
    • En Fecha de inicio, ingresa una fecha en el formato YYYY-MM-DD. La transferencia de datos carga los datos de Stripe a partir de esta fecha.
    • Selecciona Sincronizar todas las cuentas conectadas para sincronizar todas las cuentas conectadas.
    • En Objetos de Stripe que se transferirán, ingresa los nombres de los objetos de Stripe que deseas transferir o haz clic en Explorar y selecciona los objetos que deseas transferir.
  5. En la sección Configuración de destino, en Conjunto de datos, selecciona el conjunto de datos que creaste para almacenar tus datos.

  6. En la sección Nombre de la configuración de transferencia, en Nombre visible, ingresa el nombre de la transferencia de datos.

  7. En la sección Opciones de programación, haz lo siguiente:

    • En la lista Frecuencia de repetición, selecciona una opción para especificar la frecuencia con la que se ejecuta esta transferencia de datos. Para especificar una frecuencia de repetición personalizada, selecciona Personalizada. Si seleccionas A pedido, esta transferencia se ejecuta cuando activas la transferencia de forma manual.
    • Si corresponde, selecciona Comenzar ahora o Comenzar a una hora determinada y proporciona una fecha de inicio y una hora de ejecución.
  8. Opcional: En la sección Opciones de notificación, haz lo siguiente:

    • Para habilitar las notificaciones por correo electrónico, haz clic en el botón de activación Notificación por correo electrónico. Después de habilitar esta opción, el administrador de transferencias recibirá una notificación por correo electrónico cuando falle la ejecución de una transferencia.
    • Si quieres habilitar las notificaciones de ejecución de transferencias de Pub/Sub para esta transferencia, haz clic en el botón de activación Notificaciones de Pub/Sub. Puedes seleccionar el nombre del tema o hacer clic en Crear un tema para crear uno.
  9. Haz clic en Guardar.

bq

Ingresa el comando bq mk y suministra la marca de creación de transferencias --transfer_config.

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=DISPLAY_NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Aquí:

  • PROJECT_ID (opcional): Es el ID del proyecto de Google Cloud . Si no se proporciona --project_id para especificar un proyecto en particular, se usa el proyecto predeterminado.
  • DATA_SOURCE: La fuente de datos: stripe.
  • DISPLAY_NAME: el nombre visible de la configuración de transferencia de datos. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si es necesario hacerle modificaciones más tarde.
  • DATASET es el conjunto de datos de destino para la configuración de transferencia.
  • PARAMETERS son los parámetros de la configuración de transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}' Los siguientes son los parámetros para una transferencia de datos de Stripe:

    • assets: Es una lista de objetos de Stripe que se incluirán en esta transferencia.
    • connector.accountId: Es el ID de la cuenta de Stripe.
    • connector.secretKey: Es la clave de API de la cuenta de Stripe.
    • connector.syncAllConnectedAccounts: Especifica true para sincronizar todas las cuentas conectadas.
    • connector.startDate: Ingresa una fecha en el formato YYYY-MM-DD. La transferencia de datos carga los datos de Stripe a partir de esta fecha.

Por ejemplo, el siguiente comando crea una transferencia de datos de Stripe en el proyecto predeterminado con todos los parámetros obligatorios:

  bq mk \
      --transfer_config \
      --target_dataset=mydataset \
      --data_source=stripe \
      --display_name='My Transfer' \
      --params= ' {
  "assets" : [ "Customers" , "Accounts", "BalanceSummaryReport"] ,
  "connector.accountId" : "acct_000000000000",
  "connector.secretKey" : "sk_test_000000000",
  "connector.syncAllConnectedAccounts" : "true",
  "connector.startDate": "2025-05-20"
  }'

API

Usa el método projects.locations.transferConfigs.create y proporciona una instancia del recurso TransferConfig.

Cuando guardas la configuración de transferencia, el conector de Stripe activa automáticamente una ejecución de transferencia según la opción de programación que elijas. Con cada ejecución de transferencia, el conector de Stripe transfiere todos los datos disponibles de Stripe a BigQuery.

Para ejecutar de forma manual una transferencia de datos fuera de tu programa habitual, puedes iniciar una ejecución de reabastecimiento.

Asignación de tipos de datos

En la siguiente tabla, se asignan los tipos de datos de Stripe a los tipos de datos de BigQuery correspondientes.

Tipo de datos de Stripe Tipo de datos de BigQuery Notas
String STRING
Dictionary STRING Cuando se carga un objeto anidado en BigQuery, se convierte en un objeto plano. Luego, este objeto aplanado se guarda como una sola cadena literal dentro de la tabla.
Integer INT64
Double DOUBLE
Float FLOAT
Decimal BIGNUMERIC
BigInt (long) BIGNUMERIC
Boolean BOOL
Datetime TIMESTAMP
Unix timestamp TIMESTAMP

Objetos con compatibilidad con el filtro StartDate

Los siguientes objetos de Stripe admiten el filtro StartDate, que te permite cargar datos basados en el tiempo:

  • Cuentas
  • Cargos
  • Cupones
  • Clientes
  • Disputas
  • InvoiceItems
  • Facturas
  • PaymentIntent
  • Pagos
  • Planes
  • Precios
  • Productos
  • PromotionCodes
  • Reembolsos
  • ShippingRates
  • Suscripciones
  • TaxRates
  • TopUps
  • Transferencias
  • ValueListItems
  • ValueLists

Soluciona problemas con la configuración de una transferencia

Si tienes problemas para configurar tu transferencia de datos, consulta Problemas de transferencia de Stripe.

Precios

No se aplican costos por transferir datos de Stripe a BigQuery mientras esta función está en vista previa.

¿Qué sigue?