Skip to main content
O CreditLedgerEntry registra cada movimento financeiro de um CreditGrant. Ele cria rastreabilidade para concessão, reserva, captura, liberação, expiração, ajuste e estorno do crédito.

​
Campos

CampoTipoDescrição
creditLedgerEntryIdUUIDIdentificador único
creditGrantIdUUIDCrédito movimentado
organizationIdUUIDOrganização da Company do crédito
companyIdUUIDCompany responsável pelo crédito
customerIdUUIDCustomer beneficiado pelo movimento
checkoutIdUUID?Checkout relacionado ao movimento, quando existir
orderIdUUID?Pedido relacionado ao movimento, quando existir
ticketIdUUID?Passagem relacionada ao movimento, quando existir
typeCreditLedgerEntryTypeTipo do movimento
amountIntValor do movimento em centavos
availableAfterIntValor disponível do CreditGrant após o movimento
referenceTypeString?Tipo de referência externa ou interna que originou o movimento
referenceIdString?Identificador da referência que originou o movimento
idempotencyKeyString?Chave usada para evitar duplicidade do movimento
createdByUUID?Usuário que criou o movimento, quando aplicável
createdAtDateTimeData de criação do movimento

​
Relacionamentos

​
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

ValorDescrição
GRANTEntrada inicial do valor concedido
RESERVEReserva temporária para checkout em andamento
CAPTUREUso confirmado em compra paga
RELEASELiberação de reserva não capturada
REFUNDEstorno de valor usado em compra cancelada
EXPIREBaixa de valor vencido
ADJUSTMENTAjuste administrativo rastreado

​
Example

{
  "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"
}