> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```graphql theme={null}
query GetTransactions {
  getTransactions {
    transactions {
      recordId
      transactionType
      amount
      status
      channel
      connectedAppId
      connectedAppName
      createdAt
    }
    totalCount
    hasNextPage
  }
}
```

<br />

***

## Estructura de la consulta

```graphql theme={null}
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

```graphql theme={null}
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

```graphql theme={null}
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**:

```graphql theme={null}
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**:

```graphql theme={null}
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**:

```graphql theme={null}
# 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**:

```graphql theme={null}
filter: {
  finalAmountGte: 25.00
}
```

***

#### Filtros de cashback

##### `cashbackAmount`, `cashbackAmountGte`, `cashbackAmountLte`

**Tipo**: `Float`\
**Descripción**: Filtra por monto de cashback ganado.

**Ejemplo**:

```graphql theme={null}
# 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**:

```graphql theme={null}
# 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**:

```graphql theme={null}
# 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**:

```graphql theme={null}
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**:

```graphql theme={null}
filter: {
  merchantId: ["550e8400-e29b-41d4-a716-446655440000"]
}
```

##### `merchant`

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

**Ejemplo**:

```graphql theme={null}
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`

<br />

**Ejemplo**:

```graphql theme={null}
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**:

```graphql theme={null}
filter: {
  channel: ["WEB", "MOBILE"]
}
```

##### `category`

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

**Ejemplo**:

```graphql theme={null}
filter: {
  category: ["Shopping", "Travel"]
}
```

***

#### Filtros de tarjeta virtual

##### `virtualCardProgram`

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

**Ejemplo**:

```graphql theme={null}
filter: {
  virtualCardProgram: ["TRANSPECOS", "SUTTON"]
}
```

##### `virtualCard`

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

**Ejemplo**:

```graphql theme={null}
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**:

```graphql theme={null}
filter: {
  fundingSource: ["Visa"]
}
```

##### `referenceId`

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

**Ejemplo**:

```graphql theme={null}
filter: {
  referenceId: "1000123"
}
```

##### `liabilityId`

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

***

## Paginación

### OffsetInput

```graphql theme={null}
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**:

```graphql theme={null}
paginate: {
  limit: 20
  offset: 0
}
```

**Ejemplo - Página 2**:

```graphql theme={null}
paginate: {
  limit: 20
  offset: 20
}
```

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

```graphql theme={null}
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

```graphql theme={null}
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`](/features/add-expense-details) 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`](/features/add-expense-details) 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`](/features/add-expense-details) 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**:

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

**Respuesta**:

```json theme={null}
{
  "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**:

```graphql theme={null}
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**:

```graphql theme={null}
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**:

```json theme={null}
{
  "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**:

```graphql theme={null}
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**:

```graphql theme={null}
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**:

```graphql theme={null}
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**:

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

**La respuesta muestra hasNextPage=true**:

```json theme={null}
{
  "data": {
    "getTransactions": {
      "transactions": [...],
      "totalCount": 150,
      "hasNextPage": true
    }
  }
}
```

**Consulta - Obtener la segunda página**:

```graphql theme={null}
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

```json theme={null}
{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}
```

**Estado HTTP**: 401 No autorizado

***

#### Permisos insuficientes

```json theme={null}
{
  "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

```json theme={null}
{
  "errors": [
    {
      "message": "Invalid date format for createdGte",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}
```

**Estado HTTP**: 400 Solicitud incorrecta

***

#### Límite de tasa excedido

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```graphql theme={null}
# 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:

```graphql theme={null}
# 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:

```javascript theme={null}
// 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:

```graphql theme={null}
# 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

```typescript theme={null}
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

```python theme={null}
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

```bash theme={null}
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`?

**R**:

* `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:

```graphql theme={null}
filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}
```

***

## Soporte

* **Estado de la API**: [https://status.fluz.app](https://status.fluz.app)
* **Portal para desarrolladores**: [https://developers.fluz.app](https://developers.fluz.app)
* **Correo de soporte**: [api-support@fluz.app](mailto:api-support@fluz.app)
* **Comunidad en Slack**: [https://fluz-dev.slack.com](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](mailto:api-support@fluz.app) o visita nuestro [Developer Portal](https://developers.fluz.app).