> ## 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.

# Registro de cambios

> Actualizaciones recientes, incorporaciones y cambios incompatibles con versiones anteriores en la API de Fluz.

<Note>
  Suscríbete a las actualizaciones en la [Página de estado de Fluz](https://you-up.fluz.app/) para incidentes y notificaciones proactivas de cambios. También puedes suscribirte a este registro de cambios vía [RSS](/changelog/rss.xml).
</Note>

<Update label="v0.0.65" tags={["Added"]} description="Julio 2026">
  * Nuevo endpoint de la API que expone transacciones rechazadas relacionadas con la cuenta. Consulta [Obtener transacciones rechazadas](/features/get-decline-transactions).
</Update>

<Update label="v0.0.62" tags={["Added"]} description="Junio 2026">
  * Se agregó compatibilidad con Plaid Link.
  * Se actualizó la página de Descripción general con información de `llms.txt`.
  * Encabezado actualizado con enlace de IA a `llms.txt`.
</Update>

<Update label="v0.0.60" tags={["Added"]} description="Mayo 2026">
  * Nueva **query** `getCardProvisioningUrl` — genera una URL corta de un solo uso que, al abrirse en un dispositivo móvil, lanza Fluz y agrega una tarjeta virtual a Apple Pay (iOS) o Google Pay (Android). Muéstrala como código QR, SMS, email o botón en la app. Cada URL expira \~5 minutos después de su creación. Requiere el alcance `CREATE_VIRTUALCARD`.
  * Nueva entrada `GetCardProvisioningUrlInput { offerId, platform }`.
  * Nuevo enum `ProvisioningPlatform` (`IOS` | `ANDROID` | `OTHER`) — controla únicamente el fallback en escritorio / dispositivo desconocido; las aperturas en iOS y Android se enrutan automáticamente.
  * Nuevo tipo de retorno `CardProvisioningUrl { url, expiresAt }`.
</Update>

<Update label="v0.0.59" tags={["Improved"]} description="Mayo 2026">
  * Se añadieron ejemplos a [Generar enlaces para compartir](/features/generate-share-links).
</Update>

<Update label="v0.0.58" tags={["Added"]} description="Mayo 2026">
  * Se agregó la mutación `addVirtualCardAddress` para guardar direcciones de facturación para la emisión de tarjetas virtuales.
  * Se actualizó la mutación `createVirtualCard` para admitir la creación de tarjetas en nombre de usuarios autorizados.
  * Se añadió el flujo completo usando `registerUser`, `addAuthorizedUser`, `addVirtualCardAddress` y `createVirtualCard`.
  * Reintenta aprobaciones pendientes del emisor con `VC-0020` y `addressId` devuelto.
</Update>

<Update label="v0.0.57" tags={["Added"]} description="Mayo 2026">
  * `redeemFluzGiftCard` — Canjear una Fluz Gift Card usando un código. Acredita `giftCardCashBalance`. Requiere `MAKE_DEPOSIT`. Consulta [Canjear una Fluz Gift Card](/features/redeem-fluz-gift-card).
  * `unlockVirtualCard` — Desbloquear una tarjeta virtual previamente bloqueada para restaurar la capacidad de transacción. Requiere `EDIT_VIRTUALCARD`. Consulta [Desbloquear una tarjeta virtual](/features/unlock-virtual-card).
</Update>

<Update label="v0.0.55" tags={["Improved"]} description="Mayo 2026">
  **Webhooks relacionados con transacciones**

  * Se agregó la descripción para los webhooks `TRANSACTION_CREATE`, `TRANSACTION_UPDATE` y `TRANSACTION_DECLINE`.
  * Se incluyeron nuevos campos después del enriquecimiento del webhook (relacionados con MCC, `virtualCardId`, etc.).
</Update>

<Update label="v0.0.54" tags={["Added"]} description="Mayo 2026">
  * Se agregaron `mcc`, `merchantCountryCode`, `originalCurrencyCode`, `originalCurrencyAmount` y `currencyConversionRate` a `VirtualCardTransaction`. Ahora los devuelve `getVirtualCardTransactions`.
  * Se hizo opcional `virtualCardIds` en `getVirtualCardTransactions` — omítelo para consultar transacciones de todas las tarjetas en la cuenta autenticada. Se agregaron filtros `dateRangeStart` y `dateRangeEnd`. `limit` predeterminado de 100 cuando se omite `virtualCardIds`; `limit` está limitado a 500. `transactionAmount` ahora puede ser nulo para filas sin un monto liquidado (p. ej., registros de rechazo solo AVS).
  * Se agregaron `usePrepaymentBalance` y `useRewardsBalance` a `CreateVirtualCardInput`. Ahora aceptado por `createVirtualCard`. Ambos predeterminados a `true` (se conserva el comportamiento existente). Establece ambos en `false` para restringir una tarjeta a extraer solo de la `userCashBalanceId` especificada, excluyendo fondos prepagos (tarjeta de regalo) y recompensas.
</Update>

<Update label="v0.0.53" tags={["Added"]} description="Abril 2026">
  * Se agregaron `shortDescription` (Merchant) y `termsAndConditions` (Offer). Ahora devueltos por `getMerchants` y `getOfferQuote`.
  * Se agregó `deliveryFormat` (GiftCard). Ahora devuelto por `getGiftCards` — utiliza `deliveryFormat` para tarjetas compradas.
</Update>

<Update label="v0.0.52" tags={["Added"]} description="Abril 2026">
  * Nueva mutación `setVirtualCardPIN`, que permite a un usuario establecer su NIP en tarjetas virtuales elegibles. Consulta [Establecer el NIP de una tarjeta virtual](/recipes/set-virtual-card-pin).
</Update>

<Update label="v0.0.51" tags={["Added"]} description="Abril 2026">
  * Nuevas consultas `getUserCashBalances` y `getUserCashBalanceById`. Estas consultas permiten a un usuario recuperar una lista de sus cuentas de gasto y una cuenta de gasto específica creada en su cuenta.
</Update>

<Update label="v0.0.49" tags={["Added"]} description="Abril 2026">
  **API para compartir tarjetas virtuales**

  * Nueva capacidad de "Compartir tarjetas virtuales" bajo Administrar tarjetas virtuales. Contacta a ventas para obtener acceso.
  * Se agregó el alcance `CREATE_SHARE_LINK` a la página de [alcances de la aplicación](/fluz-dashboard/application-scopes).
</Update>

<Update label="v0.0.45" tags={["Added"]} description="Febrero 2026">
  **API de registro de empresas**

  * Nueva query `getBusinessCategories: [BusinessCategory]` para recuperar categorías de negocio, con tipos de respuesta `BusinessCategory` y `BusinessSubCategory`.
  * Nueva mutación `registerBusiness(input: RegisterBusinessInput!): RegisterBusinessResult` para el registro programático de empresas.
  * Nuevos tipos de entrada: `RegisterBusinessInput`, `BusinessLegalAddressInput`, `BusinessOwnerInput`, `OwnerAddressInput`.
  * Nuevos enums: `BusinessStructure` (`LLC`, `CORPORATION`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `COOP`) y `BusinessAccountUsage`.
  * Nuevos tipos de respuesta: `RegisterBusinessResult { accountId, kybStatus, success, error }` y `RegisterBusinessError { message, code }`.
  * Ambas operaciones requieren autenticación con el alcance OAuth `REGISTER_BUSINESS`.
</Update>

<Update label="v0.0.44" tags={["Improved"]} description="Enero 2026">
  **Actualizaciones a la query `getMerchants`**

  * La query `getMerchants` ahora devuelve correctamente todas las ofertas disponibles.
  * La query `getMerchants` ahora puede devolver un campo `exclusiveRateId` (dentro del objeto `offers`). Este valor puede usarse en `purchaseGiftCard` para especificar la oferta de tarifa exclusiva con la que deseas comprar.
</Update>

<Update label="v0.0.43" tags={["Added"]} description="Diciembre 2025">
  **APIs de Retiros y Cuentas de gasto**

  * Se agregó la mutación `withdrawCashBalance` con el requisito de alcance `MAKE_WITHDRAWAL`.
  * Se agregó el enum `WithdrawMethods` con soporte para los métodos `PAYPAL`, `BANK_ACH`, `BANK_CARD` y `VENMO`.
  * Se agregó el enum `WithdrawSource` con soporte para fuentes `CASH_BALANCE` y `REWARDS_BALANCE`.
  * Se agregó `WithdrawCashBalanceInput` con soporte de idempotencia, además de los tipos `Withdraw` y `WithdrawCashBalanceResponse` con detalles completos del registro de retiro, incluidas comisiones, estado y marcas de tiempo.
  * Se agregó la mutación `transferUserCashBalance` con el requisito de alcance `MAKE_INTERNAL_TRANSFER`, además de los tipos `TransferInternalBalanceInput` y `TransferInternalBalanceResponse`.
  * Se agregó `userCashBalanceId` a `EditVirtualCardInput` para habilitar el cambio de la fuente de fondos a una cuenta de gasto especificada mediante `editVirtualCard`.
  * Se agregó `userCashBalanceIds` a `TransactionFilterInput` para filtrar transacciones por cuentas de gasto mediante `getTransactions`, y `userCashBalanceId` a `getGiftCards` para filtrar tarjetas de regalo por cuenta de gasto.
  * Se agregaron las mutaciones `updateUserCashBalance` y `closeUserCashBalance` con el requisito de alcance `MANAGE_PAYMENT`, además de los tipos de entrada y respuesta de soporte (`UpdateUserCashBalanceInput`, `CloseUserCashBalanceInput`, `CloseUserCashBalanceResponse`, `ClosedUserCashBalance`, `CloseUserCashBalanceResponseVirtualCard`).
  * Se agregó registro de acciones de la aplicación para la pista de auditoría.
</Update>

<Update label="v0.0.42" tags={["Added"]} description="Noviembre 2025">
  * Se agregó un nuevo campo `userCashBalances` al tipo `UserBalances` en la query `getWallet`. Devuelve información detallada sobre cuentas individuales de saldo en efectivo del usuario con paginación vía `paginate` (limit/offset), ordenadas por fecha de creación (más reciente primero). Incluye `userCashBalanceId`, `totalCashBalance`, `availableCashBalance`, `lifetimeCashBalance`, `nickname`, `status` y `createdAt` — lo que permite el seguimiento de múltiples cuentas de saldo en efectivo por usuario con apodos personalizados y monitoreo de estado.
</Update>

<Update label="v0.0.40" tags={["Added"]} description="Noviembre 2025">
  * Se agregó un nuevo campo `userCashBalanceId` a `DepositCashBalanceInput` para especificar el saldo en efectivo (cuenta de gasto) en el que depositar los fondos.
</Update>

<Update label="v0.0.39" tags={["Added"]} description="Noviembre 2025">
  * Nuevas mutaciones para administrar tarjetas bancarias guardadas: `updateBankCardNickname`, `updateBankCardPreferredMerchantCategoryCode` y `deleteBankCard`, con los tipos de entrada correspondientes.
  * Campo `nickname` agregado al tipo `BankCard`.
  * Campos opcionales agregados a `AddBankCardInput`: `nickname` y `preferredMerchantCategoryCode` (MCC, normalizado a 4 dígitos).
</Update>

<Update label="v0.0.37" tags={["Added"]} description="Septiembre 2025">
  * `getVirtualCardBalance`: nueva query que recupera información de saldo para una lista de tarjetas virtuales, incluyendo `spentAmount`, `remainingBalance`, `spendLimit` y `spendLimitDuration`.
  * `getVirtualCardTransactions`: nueva query que recupera transacciones para una lista de tarjetas virtuales, con filtros como `transactionTypes`.
</Update>

<Update label="v0.0.36" tags={["Improved"]} description="Septiembre 2025">
  * La query `getUserPurchases` ahora incluye la capacidad de filtrar las compras devueltas en la respuesta mediante una nueva variable opcional `UserPurchaseFilterInput`. Filtra compras realizadas por el usuario, la cuenta o ambos.
</Update>

<Update label="v0.0.35" tags={["Added"]} description="Septiembre 2025">
  * La respuesta de la mutación `revealVirtualCardByVirtualCardId` ahora incluye un nuevo campo `authorizationSetting`.
  * **API de tarjetas virtuales en lote**: nueva API para crear y administrar una gran cantidad de tarjetas virtuales de forma asíncrona.
  * **Mutación** `createVirtualCardBulkOrder`: envía una orden en lote y recibe un `orderId` único.
  * **Query** `getVirtualCardBulkOrderStatus`: sondea para rastrear el estado de la orden y recuperar los detalles de las tarjetas al completarse.
  * El proceso de creación de tarjetas en lote es asíncrono — verifica el estado de la orden para recuperar los detalles de las tarjetas.
</Update>

<Update label="v0.0.32" tags={["Added"]} description="Julio 2025">
  * **Nueva query `getVirtualCardOffers`**: lista integral de todas las ofertas activas de tarjetas virtuales disponibles para creación, incluyendo `offerId` (esencial para la creación de la tarjeta), `programName`, `bankName`, `rewardValue` y límites detallados del programa (límites de gasto diarios, semanales y mensuales).
  * **Mutación actualizada `createVirtualCard`**: emite tarjetas virtuales por medio de programación proporcionando un `offerId` (de `getVirtualCardOffers`), un `spendLimit` y atributos personalizables como `cardNickname` y `spendLimitDuration`.
  * **Nueva mutación `editVirtualCard`**: actualiza parámetros clave de una tarjeta virtual existente — `spendLimit`, `spendLimitDuration`, `lockDate`, `lockCardNextUse` y `cardNickname`.
  * **Nueva mutación `lockVirtualCard`**: bloquea inmediatamente una tarjeta virtual, evitando cualquier transacción posterior.
</Update>

<Update label="v0.0.31" tags={["Added"]} description="Julio 2025">
  * El tipo `Offer` en la respuesta de `getMerchants` ahora incluye un campo `deliveryFormat` que especifica cómo se cumple la oferta: `URL`, `CODES`, `PIN_AS_CODE` o `PIN_WITH_URL`.
  * La query `getMerchants` se ha mejorado con un nuevo argumento `filterBy`, que te permite filtrar los resultados para incluir solo comercios con ofertas que coincidan con un `deliveryFormat` específico.
</Update>

<Update label="v0.0.30" tags={["Added"]} description="2025">
  * Se mejoró la query `getMerchants` con un nuevo argumento de entrada `offerTypes`, que permite filtrar por `giftCardOffer`s, `cardLinkedOffer`s o ambos. De forma predeterminada, si no se proporciona `offerTypes`, la query devuelve solo ofertas de tarjetas de regalo.
</Update>

<Update label="v0.0.29" tags={["Added","Improved"]} description="2025">
  * Se introdujo una nueva query `getReferralUrl` que devuelve una cadena de referidos según la entrada de comercio, con un nuevo tipo `MerchantInput`.
  * Se introdujo un intento de recompra automática en la mutación `purchaseGiftCard`. Si una compra de tarjeta de regalo usando tarjeta bancaria, cuenta bancaria o PayPal falla, el sistema intenta automáticamente recomprar usando el saldo de Fluz.
  * Se introdujo el campo `defaultToBalance` en `PurchaseGiftCardInput` para configurar el saldo de Fluz como método de pago de respaldo si falla el método de pago principal. Predeterminado a `true`.
</Update>

<Update label="v0.0.27" tags={["Added","Improved"]} description="2025">
  * Se introdujo un nuevo alcance de acceso, `CREATE_VIRTUALCARD`, para crear tarjetas virtuales.
  * Se introdujo una nueva función, `createVirtualCard`, para crear tarjetas virtuales con parámetros específicos.
  * Se agregó una nueva query, `getBINs`, para recuperar los BIN asociados con tarjetas virtuales.
  * Se introdujo una entrada `merchantCategoryCode` para depósitos al saldo en efectivo, lo que permite una mejor categorización de transacciones.
  * Se agregó una nueva query, `getMccList`, para recuperar una lista de códigos de categoría de comercio.
  * Se mejoró la validación de alcances para la query `getApplicationScopes` y se mejoró la gestión de definiciones de tipos de GraphQL.
</Update>

<Update label="v0.0.26" tags={["Improved"]} description="2025">
  * Se mejoró el manejo de la información de stock para ofertas de comercios: el campo `stockInfo` del objeto `Offer` ahora devuelve `StockInfoFixedType` o `StockInfoVariableType` según si la oferta es fija o variable.
  * Se mejoró el manejo de errores con respuestas de mensajes de error más intuitivas — respuestas mejoradas para errores de `purchaseGiftCard` sin oferta y métodos de pago que no coinciden con la cuenta.
</Update>

<Update label="v0.0.17 – v0.0.21" tags={["Added","Fixed"]} description="2025">
  **v0.0.21**

  * Se introdujo un parámetro `idempotencyKey` para `depositCashBalance` y `purchaseGiftCards` para evitar solicitudes duplicadas.
  * Se agregaron los tipos `purchaseGiftCardInput` para agilizar el manejo de parámetros para transacciones.
  * Se introdujo un nuevo campo `purchaseDisplayId` en el tipo `UserPurchase`, que proporciona un ID de visualización para las compras.
  * Se corrigió el campo `offeringMerchantId` del objeto `Offer` para devolver `offering_merchant_id` en lugar de `offer_id`.

  **v0.0.20**

  * Se agregó el requisito `accountId` a `generateUserAccessToken`.
  * Se implementó una nueva query, `getAccountsByUserId`, para obtener cuentas según `userId`.
  * Se agregó un nuevo enum `AccountType` para categorizar cuentas como `CONSUMER` o `BUSINESS`, además de nuevos objetos `Account`, `Business` y `Seat`.

  **v0.0.17**

  * Se corrigió la entrada del canal de plataforma de `depositCashBalance` para que la fuente del registro de la transacción de depósito se registre como `API`.
</Update>

## Gestión de cambios

Los cambios aditivos (nuevos campos, nuevos valores de enum, nuevas operaciones) se anuncian al menos **7 días** antes del lanzamiento cuando requieren acción por parte de los integradores. Los cambios incompatibles con versiones anteriores se anuncian al menos **14 días** de antelación y normalmente se agrupan en ventanas de lanzamiento principales.

Para ver una lista completa de las operaciones de la API, consulta la [referencia de la API](https://storage.googleapis.com/fluz-public-docs/api-reference.html).