> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Sobregiro de Saldo > Habilita el Sobregiro de Saldo controlado en Midaz con división automática de operaciones, prioridad de pago del crédito y límites para cuentas BNPL o de liquidación. El Sobregiro de Saldo permite debitar un saldo más allá de sus fondos disponibles. El saldo principal nunca queda negativo. Midaz registra el déficit como **OverdraftUsed** y divide la operación entre el saldo principal y un saldo complementario interno. Cuando llegan créditos, Midaz paga primero el sobregiro. El resto va a Available. Este mecanismo admite líneas de crédito, BNPL, cuentas de liquidación, acceso al salario devengado y cualquier producto que necesite posiciones negativas controladas. ## Dirección del saldo *** Los saldos llevan un campo `direction` que define cómo los débitos y créditos afectan el saldo: | Dirección | Comportamiento | Uso típico | | --------- | --------------------------------------- | ------------------------------------------------------ | | `credit` | El débito disminuye, el crédito aumenta | Cuentas corrientes, billeteras, reservas | | `debit` | El débito aumenta, el crédito disminuye | Préstamos, seguimiento de sobregiro, cuentas por pagar | En la creación, Midaz usa un `direction` explícito cuando se proporciona, luego el `defaultDirection` del Tipo de Cuenta. Si ninguno está definido, las Cuentas externas usan `debit`. Todas las demás Cuentas usan `credit`. Defines la dirección en el momento de la creación. Es **inmutable**. El saldo complementario de sobregiro (descrito abajo) siempre usa `direction=debit`. ## Configuración del saldo *** El objeto `settings` de un saldo controla el comportamiento del sobregiro: | Campo | Tipo | Descripción | | ----------------------- | ---------------- | -------------------------------------------------------------------------------------------------------- | | `allowOverdraft` | boolean | Habilita el sobregiro en este saldo | | `overdraftLimitEnabled` | boolean | Controla si se aplica un límite | | `overdraftLimit` | string (decimal) | Monto máximo de sobregiro. Obligatorio cuando `overdraftLimitEnabled` es `true`. Debe ser mayor que `0`. | El objeto `settings` también lleva `balanceScope`. Identifica un saldo transaccional (el predeterminado) o un saldo interno gestionado por el sistema, como el complementario de sobregiro. Puedes definir `balanceScope: "transactional"` cuando creas o actualizas un saldo público. No puedes definir `balanceScope: "internal"` a través de la API pública. ## Modos de configuración *** ### Sin sobregiro (predeterminado) El comportamiento estándar. Midaz rechaza cualquier débito que supere el saldo disponible. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": false } } ``` ### Sobregiro ilimitado La posición derivada puede quedar negativa sin tope. El saldo `Available` persistido permanece en `0`, mientras Midaz registra el déficit como `OverdraftUsed`. Usa esto para cuentas de liquidación o pool, donde las posiciones negativas son normales y las concilias de forma externa. ```json JSON theme={null} { "key": "settlement", "assetCode": "USD", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": false } } ``` ### Sobregiro limitado La posición derivada puede quedar negativa hasta un límite definido. El saldo `Available` persistido permanece en `0`, mientras Midaz registra el déficit como `OverdraftUsed`. Este es el modo más común para productos de crédito al consumo. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "5000.00" } } ``` Cuando `overdraftLimitEnabled` es `true`, debes definir `overdraftLimit` como una cadena decimal positiva. Si lo omites o lo defines como `"0"`, Midaz devuelve el error `0172 - ErrInvalidBalanceSettings`. ## Cómo funciona el sobregiro *** ### División de la operación Cuando una transacción de débito supera los fondos disponibles, Midaz divide la operación automáticamente: 1. El débito consume todo el Available restante y lo deja en **0**. 2. Midaz acumula el exceso como **OverdraftUsed** en el saldo principal. 3. Si Midaz encuentra el saldo interno `"overdraft"` (descrito abajo), crea una operación complementaria. Esta operación registra el pasivo como un débito de partida doble. Si no encuentra ese saldo, Midaz omite la operación complementaria. El saldo principal igual acumula **OverdraftUsed**. **Ejemplo:** el saldo tiene Available = 300. Llega un débito de 500. | Paso | Available | OverdraftUsed | Descripción | | ------- | --------- | ------------- | ---------------------------------------------------------- | | Antes | 300 | 0 | Estado normal | | Después | 0 | 200 | 300 consumidos de Available, 200 acumulados como sobregiro | La transacción se completa como una sola operación atómica. Quien llama no necesita manejar la división. Midaz lo hace automáticamente. Si configuras un límite, Midaz compara el OverdraftUsed resultante con `overdraftLimit` **antes** de procesar la transacción. Si el resultado supera el límite, Midaz rechaza la transacción con el error `0167 - ErrOverdraftLimitExceeded`. ### Pago automático (división de devolución) Cuando llega un crédito y `OverdraftUsed > 0`, Midaz prioriza el pago: 1. Midaz aplica el crédito primero a **OverdraftUsed** y reduce la deuda. 2. Cualquier monto restante después de que OverdraftUsed llega a 0 va a **Available**. 3. Si Midaz encuentra el saldo interno `"overdraft"`, una operación complementaria en él registra el pago. Si no encuentra ese saldo, Midaz omite la operación complementaria. El crédito igual paga **OverdraftUsed** en el saldo principal. **Ejemplo:** OverdraftUsed = 200, Available = 0. Llega un crédito de 350. | Paso | Available | OverdraftUsed | Descripción | | ------- | --------- | ------------- | -------------------------------- | | Antes | 0 | 200 | Sobregiro activo | | Después | 150 | 0 | 200 pagados, 150 van a Available | El pago es automático. No puedes omitirlo. Midaz reduce las posiciones de sobregiro lo antes posible, lo que mantiene el saldo sano. ### Transacciones pendientes y sobregiro Una transacción `PENDING` crea una retención. No consume sobregiro. Si una retención superara Available, Midaz rechaza la transacción con el error `0018 - Insufficient Funds Error`. La retención rechazada no cambia Available, OnHold ni `OverdraftUsed`. Cuando cancelas una transacción pendiente, Midaz libera su retención. Una transacción pendiente creada por una versión anterior de Midaz ya puede llevar sobregiro. Midaz igual revierte ese estado heredado de forma correcta durante la cancelación. ## Posición *** Cada respuesta de saldo incluye un bloque `position` calculado. Da una vista en tiempo real del estado del saldo: | Campo | Descripción | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `available` | El `position.available` derivado. Puede ser negativo cuando el saldo persistido tiene `Available = 0` y `OverdraftUsed > 0`. | | `onHold` | Refleja `Balance.OnHold` — fondos reservados por operaciones pendientes. | | `overdraftLimitAvailable` | Margen de sobregiro restante, no negativo. Es `"0"` cuando un límite configurado se usa por completo y se omite cuando el sobregiro es ilimitado. | No guardes en caché el bloque `position` para fines contables. Midaz nunca lo persiste. Calcula el bloque en el momento de la consulta a partir del estado actual del saldo. ## Saldo complementario *** Cuando actualizas un saldo para definir `allowOverdraft` como `true` por primera vez, Midaz aprovisiona de forma automática un **saldo complementario** en la misma cuenta. El saldo complementario registra el lado del pasivo de la partida doble. Midaz lo crea una vez por cuenta y lo reutiliza en cada disposición y pago de sobregiro. | Propiedad | Valor | Por qué | | ---------------- | ------------- | --------------------------------------------------------------------------------------- | | `key` | `"overdraft"` | Clave reservada del sistema | | `direction` | `debit` | El complementario registra un pasivo — los débitos lo aumentan, los créditos lo reducen | | `scope` | `internal` | Bloquea operaciones directas de usuario | | `allowSending` | `true` | Obligatorio para operaciones DEBIT en el complementario (disposiciones de sobregiro) | | `allowReceiving` | `true` | Obligatorio para operaciones CREDIT en el complementario (pagos de sobregiro) | Este saldo está **totalmente gestionado por el sistema**: * No puedes crearlo, modificarlo ni eliminarlo a través de la API pública. * Midaz **reserva** la clave `"overdraft"`. Una solicitud que crea un saldo con esta clave devuelve el error `0170 - ErrReservedBalanceKey`. * Refleja el pasivo como un registro correcto de partida doble, de modo que el ledger permanece balanceado. El valor `scope: "internal"` bloquea las operaciones directas de usuario, sin importar los indicadores de permiso anteriores. Midaz rechaza cualquier operación directa en este saldo con el error `0168 - ErrDirectOperationOnInternalBalance`. El complementario se mueve solo mediante el enriquecimiento de sobregiro que ejecuta el sistema. ## Estado del sobregiro en las operaciones *** Cada operación expone el estado del sobregiro en los bloques `balance` y `balanceAfter`. El campo `overdraftUsed` registra el sobregiro consumido antes y después de la operación. Esto da un registro de auditoría completo sin una consulta de saldo aparte. Para las operaciones que no tocan el sobregiro, ambos valores son `"0"`. Las operaciones complementarias gestionadas por el sistema en el saldo `"overdraft"` usan `type: "OVERDRAFT"` (en mayúsculas). El campo `direction` lleva el ciclo de vida: `"debit"` para una disposición, `"credit"` para un pago. ```json Primary debit drawing overdraft theme={null} { "type": "DEBIT", "direction": "debit", "amount": { "value": "500" }, "accountAlias": "@user123", "balanceKey": "checking", "balance": { "available": "300", "onHold": "0", "version": 1, "overdraftUsed": "0" }, "balanceAfter": { "available": "0", "onHold": "0", "version": 2, "overdraftUsed": "200" } } ``` ```json Companion overdraft draw theme={null} { "type": "OVERDRAFT", "direction": "debit", "amount": { "value": "200" }, "balanceKey": "overdraft", "balance": { "available": "0", "onHold": "0", "version": 1, "overdraftUsed": "0" }, "balanceAfter": { "available": "200", "onHold": "0", "version": 2, "overdraftUsed": "200" } } ``` Tanto la operación principal como la complementaria comparten el mismo par `overdraftUsed` de antes y después. Reflejan la transición de sobregiro del saldo principal, de modo que el ciclo de vida es visible desde cualquiera de las dos filas. La columna interna `snapshot` de tipo JSONB en la tabla `operations` guarda los mismos valores para indexación y reconstrucción histórica. Esta columna no forma parte del formato JSON público. En su lugar, los valores aparecen en `balance.overdraftUsed` y `balanceAfter.overdraftUsed`. Midaz puede agregar al snapshot contexto futuro generado por el sistema sin romper el contrato público. Las operaciones complementarias heredan el `routeId` de la operación principal. Para cada ruta con capacidad de sobregiro, configura las rúbricas `debit` y `credit` de la entrada `overdraft`. Midaz exige ambas. Midaz resuelve `routeCode` y `routeDescription` a partir de la rúbrica que coincide con la dirección del complementario. ## Eventos de sobregiro *** En tiempo de ejecución, Midaz habilita la publicación de eventos de sobregiro a menos que `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` sea explícitamente `false`. El entorno de ejemplo incluido define el indicador como `false`. Un despliegue que parte de ese ejemplo no publica eventos de sobregiro hasta que lo definas como `true`. ```bash Environment theme={null} # The bundled example disables overdraft-event publication. Runtime enables it unless the flag is explicitly false. RABBITMQ_OVERDRAFT_EVENTS_ENABLED=false # Optional: route overdraft events to a dedicated exchange. # When unset, the broker's default exchange is used. RABBITMQ_OVERDRAFT_EVENTS_EXCHANGE=transaction.overdraft_events.exchange ``` ### Tipos de evento | Evento | Descripción | | ------------------- | ------------------------------------------------------------------------------ | | `overdraft.drawn` | Se consumió el sobregiro — OverdraftUsed aumentó | | `overdraft.repaid` | El sobregiro se pagó de forma parcial — OverdraftUsed disminuyó pero sigue > 0 | | `overdraft.cleared` | El sobregiro se pagó por completo — OverdraftUsed llegó a 0 | ### Ejemplo de payload del evento ```json JSON expandable theme={null} { "source": "midaz", "eventType": "balance", "action": "overdraft.drawn", "timestamp": "2026-04-28T14:30:00.000000Z", "version": "v3.0.0", "organizationId": "0198575d-f9fd-702b-bb15-fa4c980b32c7", "ledgerId": "0198575d-fa0b-7ac7-8b7d-9d3ab7dccafc", "payload": { "accountId": "0198575f-a8f9-7924-a6d7-8122f2c77ddd", "transactionId": "019b2c3d-4e5f-6789-0123-456789abcdef", "amount": "200", "overdraftBalance": "200", "timestamp": "2026-04-28T14:30:00.000000Z" } } ``` Usa los eventos de sobregiro para disparar workflows downstream: acumulación de intereses, notificaciones a clientes, alertas de riesgo o procesos de cobro automáticos. ## Casos de uso *** ### Sobregiro en cuenta corriente (cheque especial) Crédito al consumo clásico. La posición derivada de la cuenta corriente puede quedar negativa hasta un límite preaprobado. El saldo `Available` persistido permanece en `0` y el monto pendiente se registra como `OverdraftUsed`. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "2000.00" } } ``` ### Buy Now, Pay Later (BNPL) Un proveedor BNPL emite un crédito de compra contra el saldo del cliente. Esto crea una posición de sobregiro inmediata que el cliente paga en cuotas. ```json JSON theme={null} { "key": "bnpl", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "10000.00" } } ``` ### Acceso al salario devengado / Adelanto de salario Los empleados disponen contra ingresos futuros. Los créditos de nómina dejan en cero la posición de sobregiro cuando llegan. ```json JSON theme={null} { "key": "salary-advance", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "3000.00" } } ``` ### Adelanto de cuentas por cobrar de marketplace Los vendedores reciben un adelanto sobre cuentas por cobrar futuras. Midaz paga el sobregiro de forma automática a medida que llegan las liquidaciones de ventas. ```json JSON theme={null} { "key": "receivables", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "50000.00" } } ``` ### Cuentas de liquidación / pool (modo ilimitado) Las cuentas de liquidación y pool quedan negativas de forma rutinaria durante el procesamiento intradía. El sobregiro ilimitado evita rechazos artificiales mientras concilias la posición al cierre del día. ```json JSON theme={null} { "key": "settlement-pool", "assetCode": "USD", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": false } } ``` ### Líneas de crédito revolvente (B2B) Las empresas disponen y pagan desde una línea de crédito revolvente. El límite de sobregiro representa la línea de crédito total. ```json JSON theme={null} { "key": "credit-line", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "500000.00" } } ``` ### Prefinanciamiento de seguros Las aseguradoras prefinancian siniestros antes de que cierren los ciclos de cobro de primas. El sobregiro cubre la brecha entre el pago y el cobro. ```json JSON theme={null} { "key": "claims-prefin", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "100000.00" } } ``` ### Programas de fidelidad (puntos adelantados) Los clientes canjean puntos antes de ganarlos. El sobregiro registra el déficit de puntos y queda en cero a medida que los clientes acumulan nuevos puntos. ```json JSON theme={null} { "key": "loyalty-points", "assetCode": "POINTS", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "10000" } } ``` ## Reglas de protección *** El sobregiro introduce varias restricciones de inmutabilidad y de acceso para mantener la integridad del ledger: * **La dirección es inmutable.** Una vez que defines el `direction` de un saldo en la creación, no puedes cambiarlo. * **Los saldos internos bloquean las escrituras.** No puedes crear, eliminar ni actualizar el saldo complementario `"overdraft"` a través de la API pública. Un PATCH devuelve el error `0175`. * **Claves reservadas.** Midaz reserva la clave `"overdraft"` para el saldo complementario gestionado por el sistema. * **Deshabilitar el sobregiro conserva la deuda pendiente.** Puedes definir `allowOverdraft: false` mientras `OverdraftUsed > 0` para bloquear disposiciones futuras, mientras los créditos entrantes igual pagan la deuda existente. * **El límite no puede bajar del uso.** Si `OverdraftUsed = 200`, Midaz rechaza `overdraftLimit: "100"` con el error `0173`, así que primero paga hasta quedar por debajo del nuevo techo o define un límite más alto. * **Concurrencia optimista.** Las actualizaciones de saldo usan control de concurrencia por versión, y Midaz rechaza una escritura desactualizada con el error `0174`. Reintenta con la versión más reciente. Para el catálogo completo de códigos de error relacionados con el sobregiro (0167–0175), consulta la [lista de errores de Midaz](/es/reference/products/midaz/error-list). ## Próximos pasos *** * Conoce los [Saldos](/es/products/midaz/balances), la base sobre la que se construye el sobregiro. * Entiende las [Operaciones](/es/products/midaz/operations) para rastrear cómo aparecen las divisiones de sobregiro en el ledger. * Configura el [Event Publisher](/es/products/midaz/event-publisher) para consumir eventos del ciclo de vida del sobregiro. * Explora las [Transacciones](/es/products/midaz/transactions) para el panorama completo de la contabilidad de partida doble en Midaz.