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

# Credit Lifecycle

> Ciclo de vida do crédito concedido e movimentos append-only do ledger.

O ciclo de crédito usa dois conceitos:

* CreditGrant guarda o estado consolidado do crédito.
* CreditLedgerEntry guarda cada movimento de forma append-only.

## Fluxo

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: GRANT
    ACTIVE --> ACTIVE: RESERVE
    ACTIVE --> ACTIVE: RELEASE
    ACTIVE --> ACTIVE: CAPTURE
    ACTIVE --> ACTIVE: REFUND
    ACTIVE --> SUSPENDED: suspensão
    SUSPENDED --> ACTIVE: reativação
    ACTIVE --> CONSUMED: saldo usado
    ACTIVE --> EXPIRED: validade encerra
    ACTIVE --> CANCELED: cancelamento
```

## Movimentos

| Movimento    | Efeito                                                           |
| ------------ | ---------------------------------------------------------------- |
| `GRANT`      | Registra a entrada inicial do valor concedido.                   |
| `RESERVE`    | Reduz o disponível e aumenta o reservado durante checkout.       |
| `CAPTURE`    | Confirma uso do valor reservado em compra paga.                  |
| `RELEASE`    | Libera uma reserva não capturada.                                |
| `REFUND`     | Devolve valor capturado para o mesmo CreditGrant.                |
| `EXPIRE`     | Baixa o valor disponível remanescente quando a validade termina. |
| `ADJUSTMENT` | Ajuste administrativo rastreado.                                 |

## Regras

* `customerId` é obrigatório.
* O crédito só pode ser usado em Orders da mesma Company.
* O valor nunca pode ficar negativo.
* `availableAmount + reservedAmount + usedAmount` não pode ultrapassar `amount`.
* Retry de movimentos críticos deve usar idempotência.
* Ledger não é editado nem removido.
* Estorno retorna para o mesmo CreditGrant, Customer e Company.

## Compra com crédito

1. Customer inicia checkout.
2. System encontra créditos ativos do Customer para a Company do Order.
3. System reserva o valor escolhido.
4. Se o pagamento confirma, System captura a reserva.
5. Se o checkout falha, System libera a reserva.
6. Se a compra é cancelada depois, System registra estorno.

Veja a modelagem em [CreditGrant](/data-modelling/credit-grant/credit-grant).