Obtener transacciones masivas

Devuelve transacciones de tus usuarios conectados como una sola lista plana, paginada por keyset, de más reciente a más antigua. Cada fila incluye el externalReferenceId y accountId del usuario al que pertenece. No hay límite por usuario: pagina con nextCursor para recorrer cada transacción en la ventana a través de cada usuario objetivo. De forma predeterminada toma los últimos 90 días cuando no se proporciona un filtro de fecha.

Cambio incompatible. Esta consulta previamente devolvía results, una entrada por usuario objetivo, cada una con hasta 20 transacciones. Ahora devuelve una lista plana transactions con paginación por cursor. Consulta Migración desde la respuesta por objetivo.

Requisitos

Authorization: Basic <API_KEY> (la clave de API de tu aplicación)
La capacidad de API masiva en tu aplicación
Los alcances LIST_PAYMENT y LIST_PURCHASES en la concesión de cada usuario objetivo

Los errores se informan por objetivo y nunca fallan toda la solicitud. Consulta Descripción general de la API masiva para el modelo de segmentación y códigos de error.

Consulta

query GetBulkTransactions(
  $targetSpec: BulkTargetSpecInput!
  $createdGte: DateTime
  $createdLte: DateTime
  $includeMetadata: Boolean
  $limit: Int
  $after: String
  $includeTotalCount: Boolean
) {
  getBulkTransactions(
    targetSpec: $targetSpec
    createdGte: $createdGte
    createdLte: $createdLte
    includeMetadata: $includeMetadata
    limit: $limit
    after: $after
    includeTotalCount: $includeTotalCount
  ) {
    transactions {
      externalReferenceId
      accountId
      recordId
      transactionType
      amount
      status
      createdAt
      memo
      transactionCategory
    }
    errors {
      externalReferenceId
      accountId
      code
      message
    }
    totalCount
    targetCount
    succeededTargetCount
    failedTargetCount
    nextCursor
    hasMore
  }
}

Variables

{
  "targetSpec": { "mode": "SELECTED", "targets": ["your-user-001", "your-user-002"] },
  "createdGte": null,
  "createdLte": null,
  "includeMetadata": false,
  "limit": 100,
  "after": null,
  "includeTotalCount": true
}

Respuesta

{
  "data": {
    "getBulkTransactions": {
      "transactions": [
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "recordId": "rec-1",
          "transactionType": "GIFT_CARD_PURCHASE",
          "amount": 25.0,
          "status": "SETTLED",
          "createdAt": "2026-07-01T00:00:00.000Z",
          "memo": null,
          "transactionCategory": null
        },
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "recordId": "rec-2",
          "transactionType": "DEPOSIT",
          "amount": 100.0,
          "status": "SETTLED",
          "createdAt": "2026-06-30T18:12:04.000Z",
          "memo": null,
          "transactionCategory": null
        }
      ],
      "errors": [
        {
          "externalReferenceId": "your-user-002",
          "accountId": null,
          "code": "TARGET_NOT_CONNECTED",
          "message": "The id does not correspond to a user currently connected to your application."
        }
      ],
      "totalCount": 1284,
      "targetCount": 2,
      "succeededTargetCount": 1,
      "failedTargetCount": 1,
      "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2…",
      "hasMore": true
    }
  }
}

Argumentos

Argumento	Tipo	Descripción
`targetSpec`	`BulkTargetSpecInput!`	Selección de objetivos. Consulta Segmentación.
`createdGte`	`DateTime`	Solo incluye transacciones creadas en o después de este momento. Predetermina a 90 días antes de `createdLte`. No debe ser posterior a `createdLte`.
`createdLte`	`DateTime`	Solo incluye transacciones creadas en o antes de este momento. Predetermina a ahora.
`includeMetadata`	`Boolean`	También retorna `memo` y `transactionCategory`. Más lento; predetermina a `false`.
`limit`	`Int`	Máximo de transacciones en esta página. El valor predeterminado y el máximo son ambos `100`. Los valores mayores se limitan, no se rechazan.
`after`	`String`	Cursor opaco de `nextCursor` de una respuesta previa. Omite para la primera página.
`includeTotalCount`	`Boolean`	También retorna `totalCount`. Cuesta un segundo escaneo de la ventana, por lo que el valor predeterminado es `false`. Prefiere `hasMore`/`nextCursor` para manejar la paginación.

Los límites de fechas acotan los datos; limit acota una sola página. La ventana puede abarcar como máximo 365 días. Las transacciones se almacenan en particiones mensuales y cada partición en la ventana se escanea por objetivo, por lo que una ventana más amplia cuesta más por página: no es gratis. Para historiales más largos, usa la exportación.

Segmentación

targetSpec.mode es SELECTED (nombra a los usuarios en targets, usando el externalReferenceId con el que los conectaste) o ALL_CONNECTED (cada usuario con una concesión activa en tu aplicación). Los targets duplicados se eliminan. Esta consulta acepta hasta 1,000 usuarios objetivo. Para más que eso, usa la exportación asíncrona.

Campos de la respuesta

Campo	Tipo	Descripción
`transactions`	`[BulkTransaction!]!`	Esta página de transacciones a través de todos los usuarios objetivo, de más reciente a más antigua, cada una atribuida a su usuario.
`errors`	`[BulkTargetFailure!]!`	Objetivos que se omitieron o fallaron. Solo en la primera página (vacío en páginas posteriores) y limitado a una muestra de 100 para que un barrido grande no devuelva una carga útil enorme. Usa `failedTargetCount` para el total real.
`totalCount`	`Int`	Total de transacciones que coinciden con la solicitud en todas las páginas: cada objetivo, toda la ventana. Se habilita con `includeTotalCount` y solo se calcula en la primera página; `null` en caso contrario. Cuesta un segundo escaneo de la ventana, así que pídelo solo cuando necesites mostrar un total.
`targetCount`	`Int!`	Número de usuarios objetivo abordados por la solicitud.
`succeededTargetCount`	`Int!`	Número de usuarios objetivo que esta solicitud estuvo autorizada a leer: resueltos y con los alcances requeridos. Independiente del contenido de esta página: un usuario autorizado sin transacciones en la ventana aún cuenta.
`failedTargetCount`	`Int!`	Número de usuarios objetivo que no se pudieron leer. Se devuelve en cada página (a diferencia de `errors`) y es el total real incluso cuando `errors` se trunca a su muestra de 100 elementos.
`nextCursor`	`String`	Cursor opaco para la siguiente página; `null` cuando esta es la última página. Basado en keyset, por lo que es estable ante escrituras concurrentes.
`hasMore`	`Boolean!`	Si quedan más transacciones más allá de esta página.

`BulkTransaction`

Campo	Tipo	Descripción
`externalReferenceId`	`String`	Tu id de referencia para el usuario al que pertenece esta transacción.
`accountId`	`UUID!`	El id de cuenta de Fluz del usuario al que pertenece esta transacción.
`recordId`	`UUID`	Identificador único para el registro de la transacción.
`transactionType`	`String`	Etiqueta de estilo de visualización para el tipo de transacción, p. ej. `"Account Transfer - In"`. No es un enum: ver la nota abajo.
`amount`	`Float!`	El monto de la transacción.
`status`	`TransactionStatus`	`PENDING` o `SETTLED`.
`createdAt`	`DateTime`	Cuándo se creó la transacción.
`memo`	`String`	Se completa solo cuando `includeMetadata: true`.
`transactionCategory`	`String`	Se completa solo cuando `includeMetadata: true`.

Cuatro comportamientos a tener en cuenta:

transactionType es una etiqueta legible por humanos, no un enum estable: los valores se ven como "Account Transfer - In", no TRANSFER. No lo uses para lógica en el código; usa recordId y el monto/signo para la lógica, y trata este campo como texto para mostrar.
Solo se devuelven transacciones PENDING y SETTLED: se excluyen las rechazadas y otros registros no básicos, en consonancia con la superficie de transacciones de un solo usuario.
El orden es de más reciente a más antigua en todo el flujo plano (createdAt descendente, empates resueltos por recordId, luego por usuario).
Una transacción en una cuenta compartida aparece una vez por concesión que puede verla: dos filas atribuidas con el mismo recordId y diferente externalReferenceId.

BulkTransaction es un tipo específico y acotado. No es el tipo Transaction completo devuelto por la consulta de transacciones de un solo usuario: los campos anteriores son el conjunto completo. Para datos más ricos por transacción, usa la exportación asíncrona.

`BulkTargetFailure`

Campo	Tipo	Descripción
`externalReferenceId`	`String`	Tu id de referencia para el objetivo, cuando esté disponible.
`accountId`	`UUID`	El id de cuenta del objetivo, cuando el objetivo fue resuelto.
`code`	`String!`	Motivo de fallo legible por máquinas (ver abajo).
`message`	`String!`	Detalle del fallo legible por humanos.

`code`	Significado
`TARGET_NOT_CONNECTED`	El id no corresponde a un usuario actualmente conectado a tu aplicación.
`INVALID_TARGET_IDENTIFIER`	El id no es un identificador válido.
`INSUFFICIENT_SCOPE`	A la concesión del usuario le falta `LIST_PAYMENT` y/o `LIST_PURCHASES`.
`ACCOUNT_NOT_PERMITTED`	La concesión no permite esta operación en la cuenta de gasto solicitada.

Un objetivo fallido nunca hace fallar la solicitud. Selecciona ambos identificadores. externalReferenceId es null para cualquier concesión que conectaste sin uno, por lo que por sí solo puede no indicarte qué usuario falló. accountId se completa siempre que el objetivo se haya resuelto, lo cual ocurre en INSUFFICIENT_SCOPE y ACCOUNT_NOT_PERMITTED, y es null solo en TARGET_NOT_CONNECTED e INVALID_TARGET_IDENTIFIER, donde nada se resolvió. Consultar errors { externalReferenceId accountId code message } significa que cada entrada es identificable por al menos uno de los dos.

Errores a nivel de solicitud

Todo lo anterior es por objetivo. Estos rechazan toda la solicitud, devolviendo data.getBulkTransactions: null más un error de GraphQL. Ramifica por extensions.code, nunca por el texto del mensaje: la redacción puede cambiar, los códigos no.

Condición	`extensions.code`	`extensions.errorName`	`statusCode`
Ventana mayor a 365 días	`APPLICATIONS-0009`	`InvalidDateWindow`	422
`createdGte` posterior a `createdLte`	`APPLICATIONS-0009`	`InvalidDateWindow`	422
Cursor `after` mal formado o manipulado	`APPLICATIONS-0010`	`InvalidPaginationCursor`	422
Más de 1,000 usuarios objetivo	`APPLICATIONS-0008`	`TargetLimitExceeded`	422
API masiva no habilitada para tu aplicación	`APPLICATIONS-0003`	`BulkApiAccessDenied`	403
Credenciales faltantes o un esquema no-Basic	`AUTH-0002`	`InvalidCredentials`	401

Las dos fallas de fecha comparten un código: ambas significan “el rango solicitado no es utilizable”, y el message las distingue:

{
  "errors": [
    {
      "message": "The requested window exceeds the 365-day maximum. Narrow the range, or use the asynchronous transactions export for a wider pull.",
      "path": ["getBulkTransactions"],
      "extensions": {
        "errorName": "InvalidDateWindow",
        "code": "APPLICATIONS-0009",
        "statusCode": 422,
        "userFriendly": true
      }
    }
  ],
  "data": { "getBulkTransactions": null }
}

Un cursor alterado de cualquier manera — truncado, recodificado, editado a mano — falla como APPLICATIONS-0010 antes de llegar a la base de datos. Trátalo como “comenzar de nuevo desde la página uno”, no como reintento.

Paginación

Lee la primera página y luego sigue nextCursor hasta que hasMore sea false. Mantén idéntico cada otro argumento entre páginas: el cursor codifica una posición en el orden específico de esa consulta.

# Page 1: omit `after`. Read errors here — they are first-page only. Ask for totalCount only
# if you actually need it; it costs an extra scan.
{
  getBulkTransactions(targetSpec: { mode: ALL_CONNECTED }, limit: 100, includeTotalCount: true) {
    transactions { recordId externalReferenceId amount createdAt }
    errors { externalReferenceId code message }
    totalCount
    failedTargetCount
    nextCursor
    hasMore
  }
}

# Page 2+: pass the previous nextCursor.
{
  getBulkTransactions(
    targetSpec: { mode: ALL_CONNECTED }
    limit: 100
    after: "eyJjcmVhdGVkQXQiOiIyMDI2LTA2…"
  ) {
    transactions { recordId externalReferenceId amount createdAt }
    nextCursor
    hasMore
  }
}

Dado que la paginación se basa en keyset y no en offset, las transacciones escritas mientras paginas no desplazarán filas entre límites de página ni producirán duplicados.

Migración desde la respuesta por objetivo

Antes	Ahora
`results[]`, una entrada por usuario objetivo	`transactions[]`, una entrada por transacción. Agrupa del lado del cliente por `externalReferenceId` para reconstruir la forma anterior.
`results[].transactions` (`Transaction` completo)	`transactions` de nivel superior del tipo más acotado `BulkTransaction`.
`results[].error`	`errors[]`: una lista plana de objetivos fallidos, solo en la primera página, limitada a una muestra de 100.
`results[].totalCount` (por objetivo)	`totalCount` (a nivel de solicitud, opcional vía `includeTotalCount`, solo en la primera página). Ya no se devuelven totales por objetivo.
`results[].hasNextPage` (por objetivo)	`hasMore` + `nextCursor` (paginación por keyset a nivel de solicitud).
`successCount` / `failureCount`	`succeededTargetCount` / `failedTargetCount`.
20 transacciones por objetivo, límite estricto	Sin límite por usuario. `limit` (predeterminado y máximo 100) acota la página.
La ventana de 90 días era un límite estricto	90 días ahora es el valor predeterminado; el límite estricto es 365 días.
100 usuarios objetivo, límite estricto	1,000 usuarios objetivo.

Cuándo usar la exportación en su lugar

getBulkTransactions puede recorrer el historial completo paginando, por lo que la exportación es para extracciones que prefieres no paginar: más de 1,000 usuarios, ventanas mayores a un año, trabajos por lotes programados, o cuando necesitas campos más ricos por transacción de los que contiene BulkTransaction. Envía GET_TRANSACTIONS_EXPORT mediante submitBulkOperation, consulta getBulkOperationJob y descarga el NDJSON desde el resultUrl de corta duración. Consulta Operaciones masivas.

​Requisitos

​Consulta

​Variables

​Respuesta

​Argumentos

​Segmentación

​Campos de la respuesta

​BulkTransaction

​BulkTargetFailure

​Errores a nivel de solicitud

​Paginación

​Migración desde la respuesta por objetivo

​Cuándo usar la exportación en su lugar

Requisitos

Consulta

Variables

Respuesta

Argumentos

Segmentación

Campos de la respuesta

`BulkTransaction`

`BulkTargetFailure`

Errores a nivel de solicitud

Paginación

Migración desde la respuesta por objetivo

Cuándo usar la exportación en su lugar