> ## 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. # Overdraft de Saldo > Habilite o Balance Overdraft controlado no Midaz com operações de split automáticas, prioridade de reembolso de crédito e limites para contas BNPL ou de liquidação. O Balance Overdraft permite debitar um saldo além dos fundos disponíveis. O saldo primário nunca fica negativo. O Midaz rastreia o déficit como **OverdraftUsed** e divide a operação entre o saldo primário e um saldo companion interno. Quando créditos chegam, o Midaz quita o overdraft primeiro. Qualquer excedente vai para o Available. Esse mecanismo suporta linhas de crédito, BNPL, contas de liquidação, antecipação salarial e qualquer produto que precise de posições negativas controladas. ## Direção do saldo *** Os saldos possuem um campo `direction` que define como débitos e créditos afetam o saldo: | Direção | Comportamento | Uso típico | | ----------------- | ------------------------------- | ------------------------------------------------------ | | `credit` (padrão) | Débito diminui, crédito aumenta | Contas correntes, carteiras, reservas | | `debit` | Débito aumenta, crédito diminui | Empréstimos, rastreamento de overdraft, contas a pagar | Você define a direção no momento da criação. Ela é **imutável**. O saldo companion de overdraft (descrito abaixo) sempre usa `direction=debit`. ## Configurações do saldo *** O objeto `settings` no saldo controla o comportamento de overdraft: | Campo | Tipo | Descrição | | ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- | | `allowOverdraft` | boolean | Habilita overdraft neste saldo | | `overdraftLimitEnabled` | boolean | Define se um limite é imposto | | `overdraftLimit` | string (decimal) | Valor máximo de overdraft. Obrigatório quando `overdraftLimitEnabled` é `true`. Deve ser maior que `0`. | O objeto `settings` também carrega um campo `balanceScope` **gerenciado pelo sistema**. Ele separa saldos internos (como o companion de overdraft) de saldos transacionais. Você não define este campo diretamente. ## Modos de configuração *** ### Sem overdraft (padrão) O comportamento padrão. O Midaz rejeita qualquer débito que exceda o saldo disponível. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": false } } ``` ### Overdraft ilimitado O saldo pode ficar negativo sem teto. Use isso para contas de liquidação ou pool, onde posições negativas são normais e você as reconcilia externamente. ```json JSON theme={null} { "key": "settlement", "assetCode": "USD", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": false } } ``` ### Overdraft limitado O saldo pode ficar negativo até um limite definido. O modo mais comum para produtos de crédito ao consumidor. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "5000.00" } } ``` Quando `overdraftLimitEnabled` é `true`, você deve definir `overdraftLimit` como uma string decimal positiva. Se você omiti-lo ou defini-lo como `"0"`, o Midaz retorna o erro `0172 - ErrInvalidBalanceSettings`. ## Como o overdraft funciona *** ### Split de operação Quando uma transação de débito excede os fundos disponíveis, o Midaz automaticamente divide a operação: 1. O débito consome todo o Available restante e o fixa em **0**. 2. O Midaz acumula o excedente como **OverdraftUsed** no saldo primário. 3. O Midaz cria uma operação companion no saldo interno `"overdraft"` (descrito abaixo). Essa operação registra o passivo como um débito de partida dobrada. **Exemplo:** Saldo com Available = 300. Um débito de 500 chega. | Etapa | Available | OverdraftUsed | Descrição | | ------ | --------- | ------------- | ---------------------------------------------------------- | | Antes | 300 | 0 | Estado normal | | Depois | 0 | 200 | 300 consumidos do Available, 200 acumulados como overdraft | A transação é processada como uma única operação atômica. O chamador não precisa tratar o split — o Midaz faz automaticamente. Se você configurar um limite, o Midaz compara o OverdraftUsed resultante com o `overdraftLimit` **antes** de processar a transação. Se o resultado exceder o limite, o Midaz rejeita a transação com o erro `0167 - ErrOverdraftLimitExceeded`. ### Reembolso automático (refund split) Quando um crédito chega e `OverdraftUsed > 0`, o Midaz prioriza o reembolso: 1. O Midaz aplica o crédito primeiro ao **OverdraftUsed** e reduz a dívida. 2. Qualquer valor remanescente após o OverdraftUsed atingir 0 vai para o **Available**. 3. Uma operação companion no saldo `"overdraft"` registra o reembolso. **Exemplo:** OverdraftUsed = 200, Available = 0. Um crédito de 350 chega. | Etapa | Available | OverdraftUsed | Descrição | | ------ | --------- | ------------- | -------------------------------------- | | Antes | 0 | 200 | Overdraft ativo | | Depois | 150 | 0 | 200 quitados, 150 vão para o Available | O reembolso é automático. Você não pode contorná-lo. O Midaz reduz as posições de overdraft o mais cedo possível, o que mantém o saldo saudável. ### Cancelamento de transação pendente com overdraft Quando você cancela uma transação `PENDING` que consumiu overdraft, o Midaz mantém o saldo companion sincronizado com o saldo primário: 1. O cancelamento reverte o hold original e qualquer overdraft consumido durante a janela pending. `OverdraftUsed` retorna ao seu valor anterior ao hold. 2. Uma operação `CREDIT` companion no saldo `"overdraft"` reduz o passivo no valor exato consumido. 3. O Midaz aplica o cancelamento primário e o crédito companion no **mesmo batch atômico**. Os dois saldos nunca saem de sincronia. O Midaz mantém o saldo companion sincronizado com o saldo primário. Isso vale para as fases de hold, commit e cancel de qualquer transação pending que toque o overdraft. ## Position *** Toda resposta de saldo inclui um bloco computado `position`. Ele fornece uma visão em tempo real do estado do saldo: | Campo | Descrição | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `available` | `Balance.Available` menos `OverdraftUsed`. Pode ser negativo quando o overdraft está ativo. | | `onHold` | Espelha `Balance.OnHold` — fundos reservados por operações pendentes. | | `overdraftLimitAvailable` | Headroom restante de overdraft. `"0"` quando overdraft está desabilitado. Omitido quando ilimitado. Decimal positivo quando um limite está configurado. | Não faça cache do bloco `position` para fins contábeis. O Midaz nunca o persiste — ele computa o bloco no momento da consulta a partir do estado atual do saldo. ## Saldo companion *** Quando você atualiza um saldo para definir `allowOverdraft` como `true` pela primeira vez, o Midaz auto-provisiona um **saldo companion** sob a mesma conta. O saldo companion registra o lado do passivo na partida dobrada. O Midaz o cria uma única vez por conta e o reutiliza em cada draw e quitação de overdraft. | Propriedade | Valor | Por quê | | ---------------- | ------------- | ------------------------------------------------------------------------ | | `key` | `"overdraft"` | Chave reservada do sistema | | `direction` | `debit` | O companion rastreia um passivo — débitos o aumentam, créditos o reduzem | | `scope` | `internal` | Bloqueia operações diretas de usuários | | `allowSending` | `true` | Necessário para operações DEBIT no companion (consumo de overdraft) | | `allowReceiving` | `true` | Necessário para operações CREDIT no companion (quitação de overdraft) | Este saldo é **totalmente gerenciado pelo sistema**: * Você não pode criá-lo, modificá-lo ou excluí-lo pela API pública. * O Midaz **reserva** a chave `"overdraft"`. Uma requisição que cria um saldo com esta chave retorna o erro `0170 - ErrReservedBalanceKey`. * Ele espelha o passivo como um registro de partida dobrada, de modo que o ledger permanece equilibrado. O valor `scope: "internal"` bloqueia as operações diretas de usuários, independentemente das flags de permissão acima. O Midaz rejeita qualquer operação direta neste saldo com o erro `0168 - ErrDirectOperationOnInternalBalance`. O companion só se movimenta via enrichment de overdraft conduzido pelo sistema. ## Estado de overdraft nas operações *** Toda operação expõe o estado de overdraft nos blocos `balance` e `balanceAfter`. O campo `overdraftUsed` registra o overdraft consumido antes e depois da operação. Isso fornece uma trilha de auditoria completa sem uma consulta separada ao saldo. Para operações que não tocam o overdraft, ambos os valores são `"0"`. Operações companion gerenciadas pelo sistema no saldo `"overdraft"` usam `type: "OVERDRAFT"` (em maiúsculas). O campo `direction` carrega o ciclo de vida: `"debit"` para um draw, `"credit"` para um reembolso. ```json Débito primário consumindo 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 de draw de overdraft 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 a operação primária quanto a companion compartilham o mesmo par `overdraftUsed` antes/depois. Ambas espelham a transição de overdraft do saldo primário, então o ciclo de vida fica visível a partir de qualquer uma das linhas. A coluna interna `snapshot` (JSONB) na tabela `operations` armazena os mesmos valores para indexação e reconstrução histórica. Essa coluna não faz parte do JSON público. Em vez disso, os valores aparecem em `balance.overdraftUsed` e `balanceAfter.overdraftUsed`. O Midaz pode adicionar contexto futuro gerado pelo sistema ao snapshot sem quebrar o contrato público. Operações companion herdam o `routeId` da operação primária. O Midaz resolve seu `routeCode` e `routeDescription` de forma independente a partir da rubrica `overdraft` da route. Se a route não tiver um lançamento de overdraft, ambos ficam vazios. ## Eventos de overdraft *** O Midaz publica eventos de ciclo de vida no RabbitMQ quando o estado de overdraft muda. A publicação está **habilitada por padrão**. Defina a flag como `"false"` para desabilitar. ```bash Ambiente theme={null} # Desabilita a publicação de eventos de overdraft (padrão: habilitado). RABBITMQ_OVERDRAFT_EVENTS_ENABLED=false # Opcional: roteia os eventos de overdraft para uma exchange dedicada. # Quando não definido, a exchange padrão do broker é usada. RABBITMQ_OVERDRAFT_EVENTS_EXCHANGE=transaction.overdraft_events.exchange ``` ### Tipos de evento | Evento | Descrição | | ------------------- | --------------------------------------------------------------------------------- | | `overdraft.drawn` | Overdraft foi consumido — OverdraftUsed aumentou | | `overdraft.repaid` | Overdraft foi parcialmente reembolsado — OverdraftUsed diminuiu mas permanece > 0 | | `overdraft.cleared` | Overdraft foi totalmente quitado — OverdraftUsed atingiu 0 | ### Exemplo de payload do 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", "overdraftLimit": "5000.00", "timestamp": "2026-04-28T14:30:00.000000Z" } } ``` Use os eventos de overdraft para acionar workflows downstream — acúmulo de juros, notificações ao cliente, alertas de risco ou processos de cobrança automática. ## Casos de uso *** ### Cheque especial (overdraft de conta corrente) Crédito clássico ao consumidor. O saldo da conta corrente pode ficar negativo até um limite pré-aprovado. Os juros são acumulados sobre o valor em aberto. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "2000.00" } } ``` ### Buy Now, Pay Later (BNPL) Um provedor de BNPL emite um crédito de compra contra o saldo do cliente. Isso cria uma posição de overdraft imediata que o cliente quita em parcelas. ```json JSON theme={null} { "key": "bnpl", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "10000.00" } } ``` ### Antecipação salarial (Earned Wage Access) Funcionários sacam contra rendimentos futuros. Os créditos de folha de pagamento liquidam a posição de overdraft quando chegam. ```json JSON theme={null} { "key": "salary-advance", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "3000.00" } } ``` ### Antecipação de recebíveis de marketplace Vendedores recebem uma antecipação sobre recebíveis futuros. O Midaz quita o overdraft automaticamente conforme as liquidações de vendas chegam. ```json JSON theme={null} { "key": "receivables", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "50000.00" } } ``` ### Contas de liquidação / Pool (modo ilimitado) Contas de liquidação e pool rotineiramente ficam negativas durante o processamento intradiário. O overdraft ilimitado evita rejeições artificiais enquanto você reconcilia a posição no fim do dia. ```json JSON theme={null} { "key": "settlement-pool", "assetCode": "USD", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": false } } ``` ### Linhas de crédito rotativo (B2B) Empresas sacam e quitam de uma facilidade de crédito rotativo. O limite de overdraft representa a linha de crédito total. ```json JSON theme={null} { "key": "credit-line", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "500000.00" } } ``` ### Pré-financiamento de seguros Seguradoras pré-financiam sinistros antes do fechamento dos ciclos de cobrança de prêmios. O overdraft cobre o gap entre pagamento e arrecadação. ```json JSON theme={null} { "key": "claims-prefin", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "100000.00" } } ``` ### Programas de fidelidade (pontos antecipados) Clientes resgatam pontos antes de acumulá-los. O overdraft rastreia o déficit de pontos e é quitado conforme os clientes acumulam novos pontos. ```json JSON theme={null} { "key": "loyalty-points", "assetCode": "POINTS", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "10000" } } ``` ## Regras de proteção *** O overdraft introduz diversas restrições de imutabilidade e acesso para manter a integridade do ledger: * **Direção é imutável.** Depois de definir a `direction` de um saldo na criação, você não pode alterá-la. * **Saldos internos bloqueiam escritas.** Você não pode criar, excluir ou atualizar o saldo companion `"overdraft"` pela API pública — um PATCH retorna o erro `0175`. * **Chaves reservadas.** O Midaz reserva a chave `"overdraft"` para o saldo companion gerenciado pelo sistema. * **Desabilitar overdraft preserva a dívida pendente.** Você pode definir `allowOverdraft: false` enquanto `OverdraftUsed > 0` para bloquear novas saídas, enquanto os créditos recebidos continuam quitando a dívida existente. * **Limite não pode cair abaixo do uso.** Se `OverdraftUsed = 200`, o Midaz rejeita `overdraftLimit: "100"` com o erro `0173`, então quite abaixo do novo teto primeiro ou defina um limite maior. * **Concorrência otimista.** Atualizações de saldo usam controle de concorrência baseado em versão, e o Midaz rejeita uma escrita obsoleta com o erro `0174` — tente novamente com a versão mais recente. Para o catálogo completo dos códigos de erro relacionados a overdraft (0167–0175), consulte a [Lista de erros do Midaz](/pt/reference/midaz/error-list). ## Próximos passos *** * Conheça os [Saldos](/pt/midaz/balances) — a base sobre a qual o overdraft é construído. * Entenda as [Operações](/pt/midaz/operations) para rastrear como os splits de overdraft aparecem no ledger. * Configure o [Event Publisher](/pt/midaz/event-publisher) para consumir eventos de ciclo de vida do overdraft. * Explore as [Transações](/pt/midaz/transactions) para a visão completa da contabilidade de partida dobrada no Midaz.