Rastrear un trabajo en lote

Consulta periódicamente el estado y los contadores de un trabajo en lote, lee los resultados por destino y descarga el archivo de resultados.

Después de enviar una operación en lote, síguelo con dos queries: getBulkOperationJob para el estado del trabajo y contadores agregados, y getBulkOperationItems para el detalle por destino. La finalización es solo por sondeo — no hay webhooks de lote.

Disponible solo en staging por ahora.

Requisitos

Authorization: Basic <API_KEY>
La capacidad de API de lote en tu aplicación.
El trabajo debe pertenecer a tu aplicación — un id de trabajo desconocido o de otra aplicación devuelve not-found.

Query — estado del trabajo

Sondéalo hasta que status sea terminal (COMPLETED, COMPLETED_WITH_ERRORS, FAILED o CANCELLED).

query BulkJob($bulkJobId: UUID!) {
  getBulkOperationJob(bulkJobId: $bulkJobId) {
    jobId
    status
    operation
    requestedTargetCount
    acceptedItemCount
    succeededItemCount
    failedItemCount
    skippedItemCount
    resultUrl
    resultUrlExpiresAt
  }
}

{
  "data": {
    "getBulkOperationJob": {
      "jobId": "9c1e6f2a-1d4b-4a2e-8f0c-2b7e5a9d1234",
      "status": "COMPLETED_WITH_ERRORS",
      "operation": "CREATE_TRANSFER",
      "requestedTargetCount": 3,
      "acceptedItemCount": 3,
      "succeededItemCount": 2,
      "failedItemCount": 1,
      "skippedItemCount": 0,
      "resultUrl": "https://storage.googleapis.com/…",
      "resultUrlExpiresAt": "2024-06-01T15:20:00Z"
    }
  }
}

Query — resultados por destino

Paginado por cursor (100 por página) y filtrable por estado del item — filtra a FAILED para conciliar solo los fallidos, o lee resultResourceId para mapear una escritura exitosa al recurso de Fluz que produjo.

query BulkItems($bulkJobId: UUID!, $status: BulkItemStatus, $after: String) {
  getBulkOperationItems(bulkJobId: $bulkJobId, status: $status, limit: 100, after: $after) {
    totalCount
    hasNextPage
    nextCursor
    items {
      externalReferenceId
      accountId
      itemIndex
      status
      resultResourceId
      errorCode
      errorMessage
      metadataResults { recordId success errorCode errorMessage }
    }
  }
}

{
  "data": {
    "getBulkOperationItems": {
      "totalCount": 3,
      "hasNextPage": false,
      "nextCursor": null,
      "items": [
        {
          "externalReferenceId": "user-123",
          "accountId": "a1b2…",
          "itemIndex": 0,
          "status": "SUCCEEDED",
          "resultResourceId": "7453414c-e290-4bb5-9516-79b212bd84cc",
          "errorCode": null,
          "errorMessage": null,
          "metadataResults": null
        },
        {
          "externalReferenceId": "user-456",
          "accountId": "c3d4…",
          "itemIndex": 1,
          "status": "FAILED",
          "resultResourceId": null,
          "errorCode": "PT-0007",
          "errorMessage": "The sender does not have sufficient balance to complete this transfer.",
          "metadataResults": null
        }
      ]
    }
  }
}

Descargar el archivo de resultados

Seleccionar resultUrl genera una URL de descarga firmada de corta duración (~15 minutos), producida bajo demanda — sondear el estado sin ella se mantiene económico. Ábrela (o curl -L) para descargar un archivo NDJSON, una fila por destino.

Exportaciones (GET_*_EXPORT) — los saldos/transacciones exportados.
Escrituras (CREATE_TRANSFER, DEPOSIT_CASH_BALANCE) — un libro de resultados: { externalReferenceId, accountId, status, resultResourceId, resourceType, errorCode, errorMessage } por destino.

resultUrl es null hasta que el trabajo sea terminal, y para trabajos que no produjeron archivo. Solicita el campo nuevamente para una URL fresca una vez que expire (resultUrlExpiresAt).

Argumentos

Parameter	Type	Description
`bulkJobId`	`UUID!`	El id del trabajo devuelto por `submitBulkOperation`.
`status`	`BulkItemStatus`	(solo items) Filtra a `QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED` o `SKIPPED`.
`limit`	`Int`	(solo items) Tamaño de página, máximo y predeterminado 100.
`after`	`String`	(solo items) Cursor opaco de `nextCursor` de una página previa.

Campos de respuesta

Field	Description
`status` (job)	`QUEUED` → `RUNNING` → `COMPLETED` / `COMPLETED_WITH_ERRORS`, o `FAILED` / `CANCELLED`.
`succeededItemCount` / `failedItemCount` / `skippedItemCount`	Contadores agregados por item.
`resultUrl` / `resultUrlExpiresAt`	URL firmada de descarga para el archivo de resultados, y cuándo expira.
`items[].status`	`SUCCEEDED`, `FAILED` o `SKIPPED` (terminal), o `QUEUED` / `RUNNING`.
`items[].resultResourceId`	El recurso de Fluz que el item produjo en éxito (p. ej., un id de transferencia, un `cash_balance_deposit_id`).
`items[].errorCode` / `errorMessage`	Motivo legible por máquina y mensaje cuando `FAILED` o `SKIPPED`.
`items[].metadataResults`	Resultados por edición para items `UPDATE_TRANSACTION_METADATA`; `null` para otras operaciones.
`totalCount`	El conteo total de items del trabajo a través de todos los estados — no el conteo de la página filtrada.

getBulkOperationItems y el archivo de resultados son dos vistas de los mismos datos por item. Usa la query de items para conciliar programáticamente (filtra a FAILED, mapea resultResourceId); usa el archivo de resultados para extraer todo el libro de una vez para trabajos grandes.

Errores

Estas queries fallan en su totalidad solo por la solicitud en sí — un destino inválido nunca es un error de solicitud, es un resultado por item FAILED/SKIPPED (ver abajo).

Error	HTTP	When
`BulkApiAccessDenied`	403	Tu aplicación no tiene la capacidad de API de lote.
`BulkJobNotFound`	404	El id del trabajo es desconocido o pertenece a otra aplicación. Externos e inexistentes son deliberadamente indistinguibles — la respuesta no filtra nada sobre trabajos de otras apps.
`ArgumentsInvalid`	400	`getBulkOperationItems` recibió un cursor `after` malformado.

Códigos de falla por item

Un item FAILED o SKIPPED lleva un errorCode legible por máquina y un errorMessage humano. Los códigos SKIPPED se asignan al enviar (el destino nunca entró a la cola); los códigos FAILED provienen ya sea de validación al enviar o, para items aceptados, del servicio downstream en tiempo de ejecución. Cualquier operación:

`errorCode`	Meaning
`TARGET_NOT_CONNECTED`	El id no resuelve a un usuario conectado a tu aplicación.
`INVALID_TARGET_IDENTIFIER`	El id no es un identificador de destino válido.
`INSUFFICIENT_SCOPE`	A la concesión del usuario le falta un scope que la operación requiere.
`ACCOUNT_NOT_PERMITTED`	El usuario no ha permitido esta operación en la cuenta solicitada.

Solo CREATE_TRANSFER:

`errorCode`	Meaning
`SOURCE_MATCHES_DESTINATION`	`from` y `to` resolvieron a la misma cuenta.
`AMBIGUOUS_DESTINATION_CASH_BALANCE`	El usuario de destino permite múltiples cuentas de gasto sin una predeterminada — el destino es ambiguo.
downstream	En la ejecución, una falla de pago expone el propio código/mensaje del servicio de pago (p. ej., saldo insuficiente del remitente).

Solo DEPOSIT_CASH_BALANCE:

`errorCode`	Meaning
`PAYMENT_METHOD_NOT_PERMITTED`	El `bankCardId` / `bankAccountId` no pertenece al usuario de destino (falta y no-pertenece usan el mismo código — sin filtrar existencia de instrumento).
`ACCOUNT_NOT_PERMITTED`	No se encontró un cupo de cuenta de gasto para el destino, o el saldo de destino no está permitido.
`AMBIGUOUS_DESTINATION_CASH_BALANCE`	El destino permite múltiples cuentas de gasto sin una predeterminada — pasa `userCashBalanceId` en el item.
downstream	En la ejecución, una falla de depósito expone el propio código/mensaje del servicio de compra (p. ej., monto por debajo del mínimo).

Los códigos con prefijo de categoría son asignados por Fluz; una fila downstream significa que el item lleva el propio código de error del servicio ejecutor de forma literal, por lo que esos códigos están abiertos. Programa contra los códigos que manejes y trata los desconocidos como una falla genérica — lee errorMessage para la razón legible por humanos.

​Requisitos

​Query — estado del trabajo

​Query — resultados por destino

​Descargar el archivo de resultados

​Argumentos

​Campos de respuesta

​Errores

​Códigos de falla por item

Requisitos

Query — estado del trabajo

Query — resultados por destino

Descargar el archivo de resultados

Argumentos

Campos de respuesta

Errores

Códigos de falla por item