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

# CreditLedgerEntry

> Movimento imutável de crédito concedido

O `CreditLedgerEntry` registra cada movimento financeiro de um [CreditGrant](/data-modelling/credit-grant/credit-grant). Ele cria rastreabilidade para concessão, reserva, captura, liberação, expiração, ajuste e estorno do crédito.

## Campos

| Campo                 | Tipo                    | Descrição                                                      |
| --------------------- | ----------------------- | -------------------------------------------------------------- |
| `creditLedgerEntryId` | `UUID`                  | Identificador único                                            |
| `creditGrantId`       | `UUID`                  | Crédito movimentado                                            |
| `organizationId`      | `UUID`                  | Organização da Company do crédito                              |
| `companyId`           | `UUID`                  | Company responsável pelo crédito                               |
| `customerId`          | `UUID`                  | Customer beneficiado pelo movimento                            |
| `checkoutId`          | `UUID?`                 | Checkout relacionado ao movimento, quando existir              |
| `orderId`             | `UUID?`                 | Pedido relacionado ao movimento, quando existir                |
| `ticketId`            | `UUID?`                 | Passagem relacionada ao movimento, quando existir              |
| `type`                | `CreditLedgerEntryType` | Tipo do movimento                                              |
| `amount`              | `Int`                   | Valor do movimento em centavos                                 |
| `availableAfter`      | `Int`                   | Valor disponível do CreditGrant após o movimento               |
| `referenceType`       | `String?`               | Tipo de referência externa ou interna que originou o movimento |
| `referenceId`         | `String?`               | Identificador da referência que originou o movimento           |
| `idempotencyKey`      | `String?`               | Chave usada para evitar duplicidade do movimento               |
| `createdBy`           | `UUID?`                 | Usuário que criou o movimento, quando aplicável                |
| `createdAt`           | `DateTime`              | Data de criação do movimento                                   |

## Relacionamentos

* Relaciona-se com [CreditGrant](/data-modelling/credit-grant/credit-grant) por `creditGrantId`.
* Relaciona-se com [Company](/data-modelling/tenant/company) por `companyId`.
* Relaciona-se com [Customer](/data-modelling/identity/customer) por `customerId`.
* Relaciona-se com [Checkout](/data-modelling/sales/checkout), [Order](/data-modelling/sales/order) e [Ticket](/data-modelling/sales/ticket), quando o movimento vem de uma compra.

## Regras de Negócio

* O ledger é append-only: registros não devem ser atualizados nem removidos depois de criados.
* `companyId`, `organizationId` e `customerId` devem repetir o escopo do CreditGrant no momento do movimento.
* `amount` positivo aumenta o valor disponível do crédito; `amount` negativo reduz o valor disponível.
* `availableAfter` deve refletir o valor disponível do CreditGrant depois da aplicação do movimento.
* `RESERVE` reduz `availableAmount` e aumenta `reservedAmount` no CreditGrant.
* `CAPTURE` reduz `reservedAmount` e aumenta `usedAmount` no CreditGrant.
* `RELEASE` desfaz uma reserva não capturada e retorna o valor para `availableAmount`.
* `REFUND` devolve valor capturado para o mesmo CreditGrant, no mesmo beneficiário e na mesma Company.
* `EXPIRE` remove o valor disponível remanescente quando a validade termina.
* `idempotencyKey` deve ser única por tipo de movimento crítico para evitar duplicidade em retry.
* Por ser imutável, o registro usa apenas `createdBy` e `createdAt` como auditoria direta.

## Enums

### CreditLedgerEntryType

| Valor        | Descrição                                     |
| ------------ | --------------------------------------------- |
| `GRANT`      | Entrada inicial do valor concedido            |
| `RESERVE`    | Reserva temporária para checkout em andamento |
| `CAPTURE`    | Uso confirmado em compra paga                 |
| `RELEASE`    | Liberação de reserva não capturada            |
| `REFUND`     | Estorno de valor usado em compra cancelada    |
| `EXPIRE`     | Baixa de valor vencido                        |
| `ADJUSTMENT` | Ajuste administrativo rastreado               |

## Example

```json theme={null}
{
  "creditLedgerEntryId": "0197f7b2-3270-78a7-a9ab-a66ebd93487a",
  "creditGrantId": "0197f7b0-9a63-720d-b4c7-e17390b3a901",
  "organizationId": "0197a801-1690-7590-b3cf-19599b9be3e4",
  "companyId": "0197a801-6a42-79aa-9e56-d3c85148c0fa",
  "customerId": "0197a7f6-4d36-7c0a-a7cb-54fcb33a3148",
  "checkoutId": "0197a812-b835-79c4-8f0b-0e3863eb6d34",
  "orderId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "ticketId": "0197a813-a9a6-7752-8173-d40a2a2d0ef0",
  "type": "CAPTURE",
  "amount": -1500,
  "availableAfter": 3500,
  "referenceType": "ORDER_PAYMENT",
  "referenceId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "idempotencyKey": "credit-capture-0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-04T14:45:00.000Z"
}
```