CreditLedgerEntry

​

Campos

​

Relacionamentos

• Relaciona-se com CreditGrant por creditGrantId.
• Relaciona-se com Company por companyId.
• Relaciona-se com Customer por customerId.
• Relaciona-se com Cooperative por cooperativeId, quando o movimento ocorre em ticket.
• Relaciona-se com TransportOperator por transportOperatorId, quando o movimento ocorre em ticket.
• Relaciona-se com Checkout e Order como contexto comercial.
• Relaciona-se com Ticket como unidade final de uso do crédito.

​

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.
• companyId identifica a empresa que concedeu o crédito; não identifica a cooperativa do ticket.
• Quando o movimento vier de um ticket, cooperativeId e transportOperatorId devem repetir o contexto operacional do Ticket/Trip.
• O uso definitivo do crédito é sempre por Ticket.
• Movimentos CAPTURE e REFUND devem preencher ticketId.
• orderId e checkoutId podem acompanhar o movimento para rastreabilidade, mas não substituem o ticketId no consumo.
• 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.
• description deve explicar movimentos manuais, ajustes e exceções operacionais quando a referência técnica não for suficiente para auditoria.
• 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.
• REFUND não devolve saldo para CompanyCreditAccount; ele recompõe o CreditGrant do Customer.
• No Checkout QR com paymentMethod = CREDIT_GRANT, a reserva e a captura exigem autorização do Customer pelo app do cliente.
• 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

​

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",
  "cooperativeId": "0197a800-24e6-76a2-90ed-ff0f6fba7b0c",
  "transportOperatorId": "01980d30-6a3c-7a42-9182-17ad6324d3aa",
  "checkoutId": "0197a812-b835-79c4-8f0b-0e3863eb6d34",
  "orderId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "ticketId": "0197a813-a9a6-7752-8173-d40a2a2d0ef0",
  "type": "CAPTURE",
  "amount": -1500,
  "availableAfter": 3500,
  "description": "Captura de crédito corporativo no ticket OAB-TKT-20260704-0001.",
  "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"
}