Fluxo
Estados da sessão
Os estados abaixo são calculados a partir delinkedAt, preparedAt, confirmedAt, canceledAt e expiresAt; não há campo status persistido na sessão.
Responsabilidades
| Etapa | Responsável | Regra |
|---|---|---|
| Criar sessão | App de venda | Usuário autenticado informa Trip e paymentMethod. |
| Vincular sessão | Customer app | Customer autenticado escaneia QR; identidade vem do token autenticado. |
| Preparar ticket | Customer app/Sales | Passageiro, itinerary, assento, promoção e crédito seguem as regras normais de checkout. |
| Confirmar dinheiro | App de venda | Usuário autenticado confirma que recebeu dinheiro. |
| Autorizar crédito | Customer app/Credit Grant | Customer autoriza uso de CreditGrant no próprio app. |
| Emitir ticket | Sales | Checkout, Order, Ticket e TripSeatSegments são criados na confirmação. |
Dinheiro vs crédito
| Aspecto | CASH | CREDIT_GRANT |
|---|---|---|
| Autorização do Customer | Scan do QR vincula a sessão | Scan do QR vincula a sessão e Customer autoriza o crédito |
| Confirmação | Canal de venda aceita o dinheiro | Credit Grant reserva e captura crédito |
| Payment | Cria Payment com method = CASH, channel do canal de venda e status = PAID | Só cria Payment se ainda houver paidAmount externo; crédito puro fica no ledger |
| Pós-venda | Prestação de contas do canal via CashSettlement | Uso fica rastreado em CreditLedgerEntry por Ticket |
Validações
- O QR Code deve pertencer a uma sessão ativa, não expirada e não confirmada.
- O Customer deve estar autenticado no app do cliente.
- A sessão só pode ser vinculada por um Customer autenticado uma vez; tentativa de trocar o vínculo deve cancelar a sessão e criar outra.
- O usuário autenticado deve estar autorizado para a Trip selecionada.
- A Trip precisa estar elegível para venda embarcada, conforme política operacional da cooperativa.
- O ticket continua exigindo itinerary, passageiro, assento disponível e regras de benefício/promoção compatíveis.
- Vendas com
paymentMethod = CREDIT_GRANTdevem validar saldo ativo do Customer e criar movimentos de reserva/captura no Credit Grant. - Vendas com
paymentMethod = CASHnão dependem de gateway e não aguardam webhook para emissão.
Dados que não devem ser persistidos
- Saldo disponível do Customer na sessão; calcular a partir de CreditGrant.
- Valor esperado da prestação de contas; calcular a partir dos Payments em dinheiro.
- Diferença de caixa; calcular a partir do esperado, declarado e recebido.
CREDIT_GRANTem PaymentMethod; crédito corporativo permanece no domínio Credit Grant.