Obtener transacciones en lote

Devuelve transacciones de tus usuarios conectados como una sola lista plana, paginada por claves, con las más recientes primero. Cada fila incluye el externalReferenceId y el 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 todos los usuarios objetivo. Por defecto usa los últimos 90 días cuando no se provee un filtro de fecha.

Cambio incompatible. Esta consulta anteriormente 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 API de tu aplicación)
La capacidad de API en lote en tu aplicación
Los alcances LIST_PAYMENT y LIST_PURCHASES en la concesión de cada usuario objetivo

Los errores se reportan por objetivo y nunca fallan toda la solicitud. Consulta Descripción general de la API en lote para el modelo de direccionamiento 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 Direccionamiento.
`createdGte`	`DateTime`	Solo incluye transacciones creadas en o después de este momento. Por defecto es 90 días antes de `createdLte`. No debe ser posterior a `createdLte`.
`createdLte`	`DateTime`	Solo incluye transacciones creadas en o antes de este momento. Por defecto es ahora.
`includeMetadata`	`Boolean`	También devuelve `memo` y `transactionCategory`. Es más lento; por defecto es `false`.
`limit`	`Int`	Máximo de transacciones en esta página. El valor por defecto y el máximo son ambos `100`. Valores mayores se limitan, no se rechazan.
`after`	`String`	Cursor opaco de `nextCursor` de una respuesta previa. Omítelo para la primera página.
`includeTotalCount`	`Boolean`	También devuelve `totalCount`. Cuesta un segundo escaneo de la ventana, por lo que su valor por defecto 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, así que una ventana más amplia cuesta más por página: no es gratis. Para historiales más largos, usa la exportación.

Direccionamiento

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 la más reciente a la más antigua, cada una atribuida a su usuario.
`errors`	`[BulkTargetFailure!]!`	Objetivos que fueron omitidos 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 enorme. Usa `failedTargetCount` para el total real.
`totalCount`	`Int`	Total de transacciones que coinciden con la solicitud a través de todas las páginas. Se activa 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 estaba autorizada a leer: resueltos y con los alcances requeridos. Independiente del contenido de esta página: un usuario autorizado sin transacciones en la ventana igual 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` en 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`	p. ej., `GIFT_CARD_PURCHASE`, `DEPOSIT`, `WITHDRAWAL`, `TRANSFER`.
`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`.

Tres comportamientos a tener en cuenta:

Solo se devuelven transacciones PENDING y SETTLED: se excluyen declinadas y otros registros no base, coincidiendo con la superficie de transacciones de un solo usuario.
El orden es de las más recientes primero 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 cada concesión que puede verla: dos filas atribuidas con el mismo recordId y diferente externalReferenceId.

BulkTransaction es un tipo estrecho y creado para un fin específico. No es el tipo Transaction completo que devuelve 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áquina (ver abajo).
`message`	`String!`	Detalle de 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.

Errores a nivel de solicitud

La solicitud completa solo se rechaza por:

Condición	Mensaje
`createdGte` posterior a `createdLte`	`createdGte must not be after createdLte.`
`after` mal formado o manipulado	`Invalid pagination cursor.`
Más de 1,000 usuarios objetivo	Límite de objetivos excedido.
Ventana mayor a 365 días	`The requested window exceeds the 365-day maximum.`

…además de los fallos habituales de autenticación y capacidad.

Paginación

Lee la primera página y luego sigue nextCursor hasta que hasMore sea false. Mantén idénticos todos los demás argumentos 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
  }
}

Como la paginación es basada 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 estrecho `BulkTransaction`.
`results[].error`	`errors[]` — una lista plana de objetivos fallidos, solo en la primera página, limitada a una muestra de 100 elementos.
`results[].totalCount` (por objetivo)	`totalCount` (para toda la 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 cursor a nivel de la solicitud).
`successCount` / `failureCount`	`succeededTargetCount` / `failedTargetCount`.
20 transacciones por objetivo, límite estricto	Sin límite por usuario. `limit` (por defecto y máximo 100) acota la página.
Ventana de 90 días, límite estricto	90 días ahora es el valor por defecto; 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, así 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 por transacción más ricos que los que ofrece BulkTransaction. Envía GET_TRANSACTIONS_EXPORT vía submitBulkOperation, consulta getBulkOperationJob y descarga el NDJSON desde el resultUrl de corta duración. Consulta Operaciones en lote.

​Requisitos

​Consulta

​Variables

​Respuesta

​Argumentos

​Direccionamiento

​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

Direccionamiento

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