Obtener todas las transacciones

Descripción general

La API de Transacciones te permite recuperar un historial completo de todas las transacciones financieras asociadas con tu cuenta. Esto incluye compras, depósitos, retiros, transferencias, pagos de facturas y todas las demás actividades financieras. Tipo de endpoint: Consulta GraphQL
Autenticación: Requerida (JWT Bearer Token)
Scopes requeridos: LIST_PAYMENT Y LIST_PURCHASES
Límite de tasa: Se aplican los límites estándar de GraphQL

Inicio rápido

Consulta básica

query GetTransactions {
  getTransactions {
    transactions {
      recordId
      transactionType
      amount
      status
      channel
      connectedAppId
      connectedAppName
      createdAt
    }
    totalCount
    hasNextPage
  }
}

Estructura de la consulta

getTransactions(
  filter: TransactionFilterInput
  paginate: OffsetInput
): TransactionConnection!

Parámetros

Parámetro	Tipo	Requerido	Descripción
`filter`	`TransactionFilterInput`	No	Criterios de filtrado para transacciones
`paginate`	`OffsetInput`	No	Parámetros de paginación (predeterminado: limit=20, offset=0)

Estructura de la respuesta

TransactionConnection

type TransactionConnection {
  transactions: [Transaction]
  totalCount: Int!
  hasNextPage: Boolean!
}

Campo	Tipo	Descripción
`transactions`	`[Transaction]`	Arreglo de registros de transacciones
`totalCount`	`Int!`	Conteo total de transacciones que coinciden con el filtro (para paginación)
`hasNextPage`	`Boolean!`	Indica si hay más resultados disponibles

Opciones de filtro

TransactionFilterInput

input TransactionFilterInput {
  # Record & Status
  recordId: [UUID]
  status: [TransactionStatus]
  
  # Amount Filters
  amount: Float
  amountGte: Float
  amountLte: Float
  finalAmount: Float
  finalAmountGte: Float
  finalAmountLte: Float
  
  # Cashback Filters
  cashbackAmount: Float
  cashbackAmountGte: Float
  cashbackAmountLte: Float
  cashbackPercentage: Float
  cashbackPercentageGte: Float
  cashbackPercentageLte: Float
  
  # Fee Filters
  feeAmount: Float
  feeAmountGte: Float
  feeAmountLte: Float
  
  # Date Filters
  createdGte: DateTime
  createdLte: DateTime
  updatedGte: DateTime
  updatedLte: DateTime
  
  # Merchant Filters
  merchantId: [UUID]
  merchant: [String]
  
  # Transaction Properties
  transactionType: [String]
  channel: [String!]
  category: [String]
  
  # Virtual Card Filters
  virtualCardProgram: [String]
  virtualCard: [UUID]
  
  # Other
  fundingSource: [String]
  userCashBalanceId: [UUID]
  referenceId: String
  liabilityId: UUID
}

Detalles de los campos de filtro

Filtros de registro y estado

`recordId`

Tipo: [UUID]
Descripción: Filtra por IDs específicos de registros de transacciones. Ejemplo:

filter: {
  recordId: ["550e8400-e29b-41d4-a716-446655440000"]
}

`status`

Tipo: [TransactionStatus]
Descripción: Filtra por estado de la transacción. Opciones:

PENDING - La transacción está siendo procesada
SETTLED - La transacción se completó exitosamente

Ejemplo:

filter: {
  status: [SETTLED]
}

Filtros por monto

`amount`, `amountGte`, `amountLte`

Tipo: Float
Descripción: Filtra por monto exacto o rango de monto en USD.

amount - Coincidencia exacta del monto
amountGte - Monto mínimo (mayor o igual)
amountLte - Monto máximo (menor o igual)

Ejemplo:

# Transactions between $10 and $500
filter: {
  amountGte: 10.00
  amountLte: 500.00
}

`finalAmount`, `finalAmountGte`, `finalAmountLte`

Tipo: Float
Descripción: Filtra por monto final (monto + comisiones). Ejemplo:

filter: {
  finalAmountGte: 25.00
}

Filtros de cashback

`cashbackAmount`, `cashbackAmountGte`, `cashbackAmountLte`

Tipo: Float
Descripción: Filtra por monto de cashback ganado. Ejemplo:

# Transactions that earned $5 or more in cashback
filter: {
  cashbackAmountGte: 5.00
}

`cashbackPercentage`, `cashbackPercentageGte`, `cashbackPercentageLte`

Tipo: Float
Descripción: Filtra por porcentaje de tasa de cashback. Ejemplo:

# Transactions with 5% or higher cashback
filter: {
  cashbackPercentageGte: 5.0
}

Filtros de comisiones

`feeAmount`, `feeAmountGte`, `feeAmountLte`

Tipo: Float
Descripción: Filtra por el monto de la comisión de la transacción. Ejemplo:

# Transactions with fees
filter: {
  feeAmountGte: 0.01
}

Filtros por fecha

`createdGte`, `createdLte`

Tipo: DateTime
Formato: ISO 8601 (p. ej., 2025-01-01T00:00:00Z)
Descripción: Filtra por rango de fecha de creación de la transacción. Ejemplo:

filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}

`updatedGte`, `updatedLte`

Tipo: DateTime
Descripción: Filtra por rango de fecha de la última actualización de la transacción.

Filtros por comercio

`merchantId`

Tipo: [UUID]
Descripción: Filtra por IDs específicos de comercios. Ejemplo:

filter: {
  merchantId: ["550e8400-e29b-41d4-a716-446655440000"]
}

`merchant`

Tipo: [String]
Descripción: Filtra por nombres de comercios (coincide con el campo destination). Ejemplo:

filter: {
  merchant: ["Amazon", "Walmart"]
}

Propiedades de la transacción

`transactionType`

Tipo: [String]
Descripción: Filtra por tipos específicos de transacción. Valores comunes:

Add Money - Depósitos
Gift Card Purchase - Compras de tarjeta de regalo
Transfer - In - Transferencias entrantes
Transfer - Out - Transferencias salientes
Virtual Card Purchase - Compras con tarjeta virtual
Withdrawal

Ejemplo:

filter: {
  transactionType: ["Gift Card Purchase", "Add Money"]
}

`channel`

Tipo: [String!]
Descripción: Filtra por el canal de la plataforma. Valores comunes:

WEB - Navegador web
MOBILE - App móvil
API - Solicitudes API

Ejemplo:

filter: {
  channel: ["WEB", "MOBILE"]
}

`category`

Tipo: [String]
Descripción: Filtra por categoría de transacción. Ejemplo:

filter: {
  category: ["Shopping", "Travel"]
}

Filtros de tarjeta virtual

`virtualCardProgram`

Tipo: [String]
Descripción: Filtra por programa/emisor de tarjeta virtual. Ejemplo:

filter: {
  virtualCardProgram: ["TRANSPECOS", "SUTTON"]
}

`virtualCard`

Tipo: [UUID]
Descripción: Filtra por IDs específicos de tarjetas virtuales. Ejemplo:

filter: {
  virtualCard: ["vc-1", "vc-2"]
}

Otros filtros

`fundingSource`

Tipo: [String]
Descripción: Busca nombres de fuentes de fondos (coincidencia parcial en origen o destino). Ejemplo:

filter: {
  fundingSource: ["Visa"]
}

`referenceId`

Tipo: String
Descripción: Filtra por ID de referencia externa (p. ej., ID visible de compra). Ejemplo:

filter: {
  referenceId: "1000123"
}

`liabilityId`

Tipo: UUID
Descripción: Filtra por ID de obligación (para pagos de facturas).

Paginación

OffsetInput

input OffsetInput {
  limit: Int = 20
  offset: Int = 0
}

Campo	Tipo	Predeterminado	Máx	Descripción
`limit`	Int	20	20	Número de transacciones a devolver por página
`offset`	Int	0	-	Número de transacciones a omitir

Ejemplo - Página 1:

paginate: {
  limit: 20
  offset: 0
}

Ejemplo - Página 2:

paginate: {
  limit: 20
  offset: 20
}

Ejemplo - Verificar si existen más páginas:

query GetTransactions {
  getTransactions(paginate: { limit: 20, offset: 0 }) {
    transactions { record_id }
    hasNextPage  # Use this to determine if there are more results
    totalCount   # Total matching records
  }
}

Tipo Transaction

type Transaction {
  record_id: UUID
  user: String!
  account_id: UUID!
  user_id: UUID
  transaction_type: String
  amount: Float!
  destination: String
  source: String
  external_funding_source_activity: Float
  fluz_balance_activity: Float
  fee: Float
  cashback: Float
  
  # Ending balances after transaction
  gift_card_prepayment_balance_available_balance: Float
  gift_card_prepayment_balance_total_balance: Float
  cash_balance_available_balance: Float
  cash_balance_total_balance: Float
  seat_balance_available_balance: Float
  seat_balance_total_balance: Float
  reserve_balance_available_balance: Float
  reserve_balance_total_balance: Float
  other_cash_balance_available_balance: Float
  other_cash_balance_total_balance: Float
  
  status: TransactionStatus
  reference_id: String
  description: String
  note: String
  category: String
  card_last_four: String
  card_display_name: String
  original_currency_amount: Float
  original_currency_code: String
  conversion_rate: Float
  merchant_id: UUID
  descriptor_id: UUID
  virtual_card_program: String
  cashback_rate: Float
  bonus_cashback_rate: Float
  channel: String
  source_type: String
  logo_url: String
  platformInstitutionLogo: String
  challengeLogoUrl: String
  invitedAccountId: UUID
  expectedClearedDate: DateTime
  liability_id: UUID
  is_gift_card_balance_affected: Boolean
  is_cash_balance_affected: Boolean
  is_seat_balance_affected: Boolean
  is_reserve_balance_affected: Boolean
  transfer_id: UUID
  used_user_cash_balance_id: UUID
  connectedAppId: UUID
  connectedAppName: String
  
  memo: String
  transactionCategory: String
  attachmentUrl: String

  created_at: DateTime
  updated_at: DateTime
}

Descripciones de campos

Campos principales de la transacción

Campo	Tipo	Descripción
`record_id`	UUID	Identificador único para este registro de transacción
`user`	String	Nombre para mostrar del usuario asociado con la transacción
`account_id`	UUID	Cuenta que es propietaria de esta transacción
`user_id`	UUID	Usuario que inició la transacción
`transaction_type`	String	Tipo de transacción (PURCHASE, DEPOSIT, etc.)
`amount`	Float	Monto principal de la transacción en USD
`source`	String	De dónde provinieron los fondos (p. ej., “Bank Card ****1234”)
`destination`	String	A dónde fueron los fondos (p. ej., nombre del comercio)
`status`	TransactionStatus	Estado actual (PENDING o SETTLED)

Detalles financieros

Campo	Tipo	Descripción
`external_funding_source_activity`	Float	Cambio en fuentes de fondos externas (tarjetas/cuentas bancarias)
`fluz_balance_activity`	Float	Cambio en saldos internos de Fluz
`fee`	Float	Comisiones cobradas por esta transacción
`cashback`	Float	Cashback obtenido de esta transacción
`cashback_rate`	Float	Porcentaje de tasa de cashback
`bonus_cashback_rate`	Float	Tasa de cashback adicional de bono

Instantáneas de saldo

Importante: Todos los campos de saldo muestran el saldo después de que se aplicó esta transacción.

Campo	Descripción
`cash_balance_available_balance`	Saldo de efectivo disponible después de la transacción
`cash_balance_total_balance`	Saldo total de efectivo después de la transacción
`seat_balance_available_balance`	Saldo de recompensas disponible después de la transacción
`seat_balance_total_balance`	Saldo total de recompensas después de la transacción
`gift_card_prepayment_balance_available_balance`	Saldo de prepago disponible después de la transacción
`gift_card_prepayment_balance_total_balance`	Saldo total de prepago después de la transacción
`reserve_balance_available_balance`	Saldo de reserva disponible después de la transacción
`reserve_balance_total_balance`	Saldo total de reserva después de la transacción
`other_cash_balance_available_balance`	Otro saldo de efectivo disponible después de la transacción
`other_cash_balance_total_balance`	Otro saldo total de efectivo después de la transacción

Detalles de la transacción

Campo	Tipo	Descripción
`reference_id`	String	Referencia externa (p. ej., ID visible de compra)
`description`	String	Descripción legible para humanos
`note`	String	Notas adicionales
`category`	String	Categoría de la transacción
`card_last_four`	String	Últimos 4 dígitos de la tarjeta usada (si aplica)
`card_display_name`	String	Nombre para mostrar del método de pago
`memo`	String	Un memo de texto libre adjunto a esta transacción. Se configura mediante `updateTransactionMetadata` o en el momento de la transacción en depósitos, compras y transferencias.
`transactionCategory`	String	Etiqueta de categoría adjunta a esta transacción. Se configura mediante `updateTransactionMetadata` o en el momento de la transacción en depósitos, compras y transferencias.
`attachmentUrl`	String	Una URL firmada para el archivo adjunto a esta transacción. Se configura mediante `updateTransactionMetadata` o en el momento de la transacción. Esta URL expira — no la almacenes. Vuelve a recuperar la transacción cuando necesites acceder al archivo.

Información del comercio

Campo	Tipo	Descripción
`merchant_id`	UUID	Identificador del comercio
`descriptor_id`	UUID	ID del descriptor de la transacción
`logo_url`	String	URL del logo del comercio/origen

Información de tarjeta virtual

Campo	Tipo	Descripción
`virtual_card_program`	String	Programa de tarjeta virtual (LITHIC, MARQETA, etc.)

Conversión de moneda

Campo	Tipo	Descripción
`original_currency_amount`	Float	Monto en la moneda original (para transacciones en el extranjero)
`original_currency_code`	String	Código de la moneda original (p. ej., “EUR”)
`conversion_rate`	Float	Tipo de cambio aplicado

Metadatos

Campo	Tipo	Descripción
`channel`	String	Canal de la plataforma (WEB, MOBILE, API)
`source_type`	String	Tipo de fuente de fondos
`liability_id`	UUID	Obligación asociada (para pagos de facturas)
`transfer_id`	UUID	Transferencia asociada (para P2P)
`used_user_cash_balance_id`	UUID	Saldo de efectivo específico usado
`is_gift_card_balance_affected`	Boolean	Indica si cambió el saldo de tarjeta de regalo
`is_cash_balance_affected`	Boolean	Indica si cambió el saldo de efectivo
`is_seat_balance_affected`	Boolean	Indica si cambió el saldo de recompensas
`is_reserve_balance_affected`	Boolean	Indica si cambió el saldo de reserva
`connectedAppId`	UUID	ID de la aplicación asociada
`connectedAppName`	String	Nombre de la aplicación asociada
`created_at`	DateTime	Cuándo se creó la transacción
`updated_at`	DateTime	Cuándo se actualizó por última vez la transacción

Ejemplos

Ejemplo 1: Lista básica de transacciones

Consulta:

query GetRecentTransactions {
  getTransactions(
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      status
      cashback
      created_at
    }
    totalCount
    hasNextPage
  }
}

Respuesta:

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "record_id": "550e8400-e29b-41d4-a716-446655440000",
          "transaction_type": "GIFT_CARD_PURCHASE",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "status": "SETTLED",
          "cashback": 2.50,
          "created_at": "2025-01-15T14:30:00Z"
        },
        {
          "record_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "transaction_type": "DEPOSIT",
          "amount": 100.00,
          "description": "Cash Balance Deposit",
          "status": "SETTLED",
          "cashback": 0.00,
          "created_at": "2025-01-14T10:15:00Z"
        }
      ],
      "totalCount": 2,
      "hasNextPage": false
    }
  }
}

Ejemplo 2: Filtrado por rango de fechas

Consulta:

query GetJanuaryTransactions {
  getTransactions(
    filter: {
      createdGte: "2025-01-01T00:00:00Z"
      createdLte: "2025-01-31T23:59:59Z"
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      status
      created_at
    }
    totalCount
    hasNextPage
  }
}

Ejemplo 3: Solo compras con saldos

Consulta:

query GetPurchaseHistory {
  getTransactions(
    filter: {
      transactionType: ["GIFT_CARD_PURCHASE"]
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      reference_id
      amount
      description
      source
      destination
      cashback
      cashback_rate
      cash_balance_available_balance
      seat_balance_available_balance
      created_at
    }
    totalCount
    hasNextPage
  }
}

Respuesta:

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "record_id": "550e8400-e29b-41d4-a716-446655440000",
          "reference_id": "1000123",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "source": "Visa ****1234",
          "destination": "Amazon",
          "cashback": 2.50,
          "cashback_rate": 5.0,
          "cash_balance_available_balance": 102.50,
          "seat_balance_available_balance": 25.00,
          "created_at": "2025-01-15T14:30:00Z"
        }
      ],
      "totalCount": 1,
      "hasNextPage": false
    }
  }
}

Ejemplo 4: Transacciones con alto cashback

Consulta:

query GetHighCashbackTransactions {
  getTransactions(
    filter: {
      cashbackPercentageGte: 5.0
      status: [SETTLED]
    }
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      cashback
      cashback_rate
      status
      created_at
    }
    totalCount
  }
}

Ejemplo 5: Filtro por rango de montos

Consulta:

query GetMediumTransactions {
  getTransactions(
    filter: {
      amountGte: 50.00
      amountLte: 200.00
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      amount
      transaction_type
      description
      created_at
    }
    totalCount
    hasNextPage
  }
}

Ejemplo 6: Transacciones con tarjeta virtual

Consulta:

query GetVirtualCardTransactions {
  getTransactions(
    filter: {
      virtualCardProgram: ["LITHIC", "MARQETA"]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      amount
      description
      virtual_card_program
      merchant_id
      status
      created_at
    }
    totalCount
  }
}

Ejemplo 7: Ejemplo de paginación

Consulta - Obtener la primera página y verificar si hay más:

query GetFirstPage {
  getTransactions(paginate: { limit: 20, offset: 0 }) {
    transactions {
      record_id
      amount
      transaction_type
    }
    totalCount
    hasNextPage
  }
}

La respuesta muestra hasNextPage=true:

{
  "data": {
    "getTransactions": {
      "transactions": [...],
      "totalCount": 150,
      "hasNextPage": true
    }
  }
}

Consulta - Obtener la segunda página:

query GetSecondPage {
  getTransactions(paginate: { limit: 20, offset: 20 }) {
    transactions {
      record_id
      amount
      transaction_type
    }
    totalCount
    hasNextPage
  }
}

Manejo de errores

Errores comunes

Token faltante o inválido

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Estado HTTP: 401 No autorizado

Permisos insuficientes

{
  "errors": [
    {
      "message": "Insufficient permissions: LIST_PAYMENT and LIST_PURCHASES scopes required",
      "extensions": {
        "code": "FORBIDDEN",
        "requiredScopes": ["LIST_PAYMENT", "LIST_PURCHASES"]
      }
    }
  ]
}

Estado HTTP: 403 Prohibido

Parámetros de filtro inválidos

{
  "errors": [
    {
      "message": "Invalid date format for createdGte",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

Estado HTTP: 400 Solicitud incorrecta

Límite de tasa excedido

{
  "errors": [
    {
      "message": "Rate limit exceeded. Please try again later.",
      "extensions": {
        "code": "RATE_LIMITED",
        "retryAfter": 60
      }
    }
  ]
}

Estado HTTP: 429 Demasiadas solicitudes

Mejores prácticas

1. Usa la paginación de forma efectiva

Siempre verifica hasNextPage para determinar si existen más resultados:

async function fetchAllTransactions() {
  const allTransactions = [];
  let offset = 0;
  const limit = 20;
  
  while (true) {
    const result = await getTransactions({ 
      paginate: { limit, offset } 
    });
    
    allTransactions.push(...result.transactions);
    
    if (!result.hasNextPage) break;
    offset += limit;
  }
  
  return allTransactions;
}

2. Solicita solo los campos necesarios

Especifica únicamente los campos que necesitas para reducir el tamaño de la respuesta:

# Good - minimal fields
getTransactions {
  transactions {
    record_id
    amount
    transaction_type
    created_at
  }
  totalCount
  hasNextPage
}

# Less efficient - requesting all 40+ fields
getTransactions {
  transactions {
    record_id
    transaction_type
    amount
    ... (all fields)
  }
}

3. Usa filtros de fecha para consultas históricas

Al consultar transacciones antiguas, utiliza siempre filtros de fecha:

# Good
filter: {
  createdGte: "2024-01-01T00:00:00Z"
  createdLte: "2024-12-31T23:59:59Z"
}

4. Cachea transacciones liquidadas

Las transacciones con status: SETTLED son inmutables y se pueden cachear:

// Example caching strategy
const cacheKey = `transactions:${accountId}:${createdGte}:${createdLte}`;
let result = cache.get(cacheKey);

if (!result) {
  result = await getTransactions({
    filter: { status: ['SETTLED'], createdGte, createdLte }
  });
  cache.set(cacheKey, result, '1 hour');
}

5. Combina filtros de forma eficiente

Usa filtros de rango para acotar resultados antes de aplicar otros filtros:

# Efficient - date range first
filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
  transactionType: ["GIFT_CARD_PURCHASE"]
  amountGte: 50.00
}

Límites de tasa

Recurso	Límite	Ventana
Consultas por usuario	100	1 minuto
Consultas por IP	300	1 minuto

Encabezados:

X-RateLimit-Limit - Máximo de solicitudes permitidas
X-RateLimit-Remaining - Solicitudes restantes en la ventana actual
X-RateLimit-Reset - Momento en que se restablece el límite (timestamp Unix)

Ejemplos de código

JavaScript/TypeScript

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://api.fluz.app/graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: `Bearer ${accessToken}`,
  },
});

const GET_TRANSACTIONS = gql`
  query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) {
    getTransactions(filter: $filter, paginate: $paginate) {
      transactions {
        record_id
        transaction_type
        amount
        description
        status
        cashback
        created_at
      }
      totalCount
      hasNextPage
    }
  }
`;

async function fetchTransactions() {
  const { data } = await client.query({
    query: GET_TRANSACTIONS,
    variables: {
      filter: {
        status: ['SETTLED'],
        createdGte: '2025-01-01T00:00:00Z',
      },
      paginate: {
        limit: 20,
        offset: 0,
      },
    },
  });
  
  return data.getTransactions;
}

Python

import requests

def get_transactions(access_token, created_gte=None, created_lte=None, limit=20, offset=0):
    url = "https://api.fluz.app/graphql"
    
    query = """
        query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) {
            getTransactions(filter: $filter, paginate: $paginate) {
                transactions {
                    record_id
                    transaction_type
                    amount
                    description
                    status
                    cashback
                    created_at
                }
                totalCount
                hasNextPage
            }
        }
    """
    
    variables = {
        "filter": {},
        "paginate": {
            "limit": limit,
            "offset": offset
        }
    }
    
    if created_gte:
        variables["filter"]["createdGte"] = created_gte
    if created_lte:
        variables["filter"]["createdLte"] = created_lte
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(
        url,
        json={"query": query, "variables": variables},
        headers=headers
    )
    
    return response.json()["data"]["getTransactions"]

# Usage
result = get_transactions(
    access_token="your_token_here",
    created_gte="2025-01-01T00:00:00Z",
    limit=20
)

print(f"Found {result['totalCount']} transactions")
print(f"Has more pages: {result['hasNextPage']}")

cURL

curl -X POST https://api.fluz.app/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) { getTransactions(filter: $filter, paginate: $paginate) { transactions { record_id transaction_type amount description status cashback created_at } totalCount hasNextPage } }",
    "variables": {
      "filter": {
        "status": ["SETTLED"],
        "createdGte": "2025-01-01T00:00:00Z"
      },
      "paginate": {
        "limit": 20,
        "offset": 0
      }
    }
  }'

Preguntas frecuentes

P: ¿Cuál es el número máximo de transacciones que puedo recuperar en una sola solicitud?

R: El límite máximo es de 20 transacciones por solicitud. Usa el campo hasNextPage para implementar la paginación.

P: ¿Hasta qué fecha llega el historial de transacciones?

R: Todas las transacciones desde la creación de la cuenta están disponibles indefinidamente.

P: ¿Se incluyen las transacciones pendientes?

R: Sí, las transacciones pendientes se incluyen por defecto. Filtra por status: [SETTLED] para excluirlas.

P: ¿En qué zona horaria están las marcas de tiempo?

R: Todas las marcas de tiempo están en UTC (formato ISO 8601).

P: ¿Qué scopes necesito?

R: Necesitas ambos scopes LIST_PAYMENT Y LIST_PURCHASES.

P: ¿Puedo filtrar por ID de usuario dentro de mi cuenta?

R: No, la API siempre devuelve todas las transacciones de tu cuenta. No hay filtrado a nivel de usuario.

P: ¿Cuál es la diferencia entre los filtros `amount` y `finalAmount`?

amount filtra el monto base de la transacción
finalAmount filtra monto + comisiones (el total cobrado al usuario)

P: ¿Cómo filtro por rango de fechas?

R: Usa createdGte y createdLte para la fecha de creación:

filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}

Soporte

Estado de la API: https://status.fluz.app
Portal para desarrolladores: https://developers.fluz.app
Correo de soporte: api-support@fluz.app
Comunidad en Slack: https://fluz-dev.slack.com

Registro de cambios

v1.0.0 (Branch: 13-fluz-15659-add-transactions-query-and-webhook-to-api)

Lanzamiento inicial de la API de consulta de Transacciones
Soporte para filtrado integral (15+ tipos de filtros)
Paginación con el tipo de respuesta TransactionConnection
Instantáneas de saldo incluidas en los registros de transacción
Requiere los scopes LIST_PAYMENT y LIST_PURCHASES
Acceso a transacciones a nivel de cuenta únicamente

¿Necesitas ayuda? Contacta a nuestro equipo de soporte para desarrolladores en api-support@fluz.app o visita nuestro Developer Portal.

Códigos de error de tarjetas de regalo Obtener transacciones de tarjetas virtuales

⌘I

​Descripción general

​Inicio rápido

​Consulta básica

​Estructura de la consulta

​Parámetros

​Estructura de la respuesta

​TransactionConnection

​Opciones de filtro

​TransactionFilterInput

​Detalles de los campos de filtro

​Filtros de registro y estado

recordId

status

​Filtros por monto

amount, amountGte, amountLte

finalAmount, finalAmountGte, finalAmountLte

​Filtros de cashback

cashbackAmount, cashbackAmountGte, cashbackAmountLte

cashbackPercentage, cashbackPercentageGte, cashbackPercentageLte

​Filtros de comisiones

feeAmount, feeAmountGte, feeAmountLte

​Filtros por fecha

createdGte, createdLte

updatedGte, updatedLte

​Filtros por comercio

merchantId

merchant

​Propiedades de la transacción

transactionType

channel

category

​Filtros de tarjeta virtual

virtualCardProgram

virtualCard

​Otros filtros

fundingSource

referenceId

liabilityId

​Paginación

​OffsetInput

​Tipo Transaction

​Descripciones de campos

​Campos principales de la transacción

​Detalles financieros

​Instantáneas de saldo

​Detalles de la transacción

​Información del comercio

​Información de tarjeta virtual

​Conversión de moneda

​Metadatos

​Ejemplos

​Ejemplo 1: Lista básica de transacciones

​Ejemplo 2: Filtrado por rango de fechas

​Ejemplo 3: Solo compras con saldos

​Ejemplo 4: Transacciones con alto cashback

​Ejemplo 5: Filtro por rango de montos

​Ejemplo 6: Transacciones con tarjeta virtual

​Ejemplo 7: Ejemplo de paginación

​Manejo de errores

​Errores comunes

​Token faltante o inválido

​Permisos insuficientes

​Parámetros de filtro inválidos

​Límite de tasa excedido

​Mejores prácticas

​1. Usa la paginación de forma efectiva

​2. Solicita solo los campos necesarios

​3. Usa filtros de fecha para consultas históricas

​4. Cachea transacciones liquidadas

​5. Combina filtros de forma eficiente

​Límites de tasa

​Ejemplos de código

​JavaScript/TypeScript

​Python

​cURL

​Preguntas frecuentes

​P: ¿Cuál es el número máximo de transacciones que puedo recuperar en una sola solicitud?

​P: ¿Hasta qué fecha llega el historial de transacciones?

​P: ¿Se incluyen las transacciones pendientes?

​P: ¿En qué zona horaria están las marcas de tiempo?

Descripción general

Inicio rápido

Consulta básica

Estructura de la consulta

Parámetros

Estructura de la respuesta

TransactionConnection

Opciones de filtro

TransactionFilterInput

Detalles de los campos de filtro

Filtros de registro y estado

`recordId`

`status`

Filtros por monto

`amount`, `amountGte`, `amountLte`

`finalAmount`, `finalAmountGte`, `finalAmountLte`

Filtros de cashback

`cashbackAmount`, `cashbackAmountGte`, `cashbackAmountLte`

`cashbackPercentage`, `cashbackPercentageGte`, `cashbackPercentageLte`

Filtros de comisiones

`feeAmount`, `feeAmountGte`, `feeAmountLte`

Filtros por fecha

`createdGte`, `createdLte`

`updatedGte`, `updatedLte`

Filtros por comercio

`merchantId`

`merchant`

Propiedades de la transacción

`transactionType`

`channel`

`category`

Filtros de tarjeta virtual

`virtualCardProgram`

`virtualCard`

Otros filtros

`fundingSource`

`referenceId`

`liabilityId`

Paginación

OffsetInput

Tipo Transaction

Descripciones de campos

Campos principales de la transacción

Detalles financieros

Instantáneas de saldo

Detalles de la transacción

Información del comercio

Información de tarjeta virtual

Conversión de moneda

Metadatos

Ejemplos

Ejemplo 1: Lista básica de transacciones

Ejemplo 2: Filtrado por rango de fechas

Ejemplo 3: Solo compras con saldos

Ejemplo 4: Transacciones con alto cashback

Ejemplo 5: Filtro por rango de montos

Ejemplo 6: Transacciones con tarjeta virtual

Ejemplo 7: Ejemplo de paginación

Manejo de errores

Errores comunes

Token faltante o inválido

Permisos insuficientes

Parámetros de filtro inválidos

Límite de tasa excedido

Mejores prácticas

1. Usa la paginación de forma efectiva

2. Solicita solo los campos necesarios

3. Usa filtros de fecha para consultas históricas

4. Cachea transacciones liquidadas

5. Combina filtros de forma eficiente

Límites de tasa

Ejemplos de código

JavaScript/TypeScript

Python

cURL

Preguntas frecuentes

P: ¿Cuál es el número máximo de transacciones que puedo recuperar en una sola solicitud?

P: ¿Hasta qué fecha llega el historial de transacciones?

P: ¿Se incluyen las transacciones pendientes?

P: ¿En qué zona horaria están las marcas de tiempo?