Passageiros - Financeiro do Passageiro

O que é

Cada passageiro de uma excursão tem um financeiro próprio (registro em excursao_passageiro_financeiro) que guarda valor original, descontos, acréscimos, valor total, valor pago, valor pendente e status. Os lançamentos (pagamentos, descontos, acréscimos, estornos) ficam em excursao_passageiro_pagamentos e alimentam o histórico.

A página de passageiros centraliza essas ações: você não precisa entrar no cartão do passageiro para registrar pagamento manual, dar baixa em uma parcela do plano PIX parcelado, conceder desconto, estornar um lançamento errado ou devolver dinheiro via reembolso. Tudo acontece pelo dropdown de Ações em cada cartão e por modais que abrem na própria listagem. O usuário normalmente chega aqui depois que o cliente paga fora do meio de pagamento (transferência, dinheiro, PIX direto) ou para resolver uma divergência de saldo.

Como usar

1. Acesse a excursão e abra a aba Passageiros (URL /admin/excursoes/{excursao}/passageiros).
2. Localize o passageiro. Use o filtro Status financeiro no topo (opções: Todos, Pendente, Parcial, Pago) para encontrar quem ainda deve.
3. No cartão do passageiro, abra o menu de Ações (botão de três pontos no canto superior direito do cartão).
4. Use a ação adequada ao caso:
   • Registrar Pagamento - para dar baixa em valor recebido.
   • Ver Histórico - para conferir totais e lançamentos antes de agir.
   • Aplicar Desconto / Aplicar Acréscimo - para ajustar o valor total.
   • Reembolsar - para devolver dinheiro já recebido.

Registrar pagamento manual

1. No dropdown de Ações, clique em Registrar Pagamento (aparece só se houver saldo pendente).
2. No modal Registrar Pagamento:
   • Valor - digite o valor recebido. Use o link Preencher total ao lado do saldo pendente para quitar de uma vez.
   • Forma de Pagamento - escolha entre PIX, Dinheiro, Cartão de Crédito, Cartão de Débito, Transferência, Boleto ou Cheque.
   • Data - data efetiva do recebimento.
   • Observação - opcional, até 500 caracteres.
3. Clique em Registrar Pagamento (botão verde).
4. O sistema recalcula valor_pago e valor_pendente, sincroniza a Order do pedido e, se o passageiro estava pendente, confirma a reserva automaticamente.

Ver histórico financeiro

1. No dropdown de Ações, clique em Ver Histórico.
2. O modal mostra:
   • Cards com Valor Original, Valor Total, Pago e Pendente.
   • Bloco de Desconto ou Acréscimo ativos com motivo, quando houver.
   • Lista de lançamentos em ordem decrescente por data, identificando forma, quem registrou, data e se foi estornado.

Aplicar desconto ou acréscimo

1. Abra Aplicar Desconto ou Aplicar Acréscimo no dropdown de Ações.
2. Informe valor (mínimo R$ 0,01) e motivo (obrigatório, até 255 caracteres).
3. Confirme. O sistema:
   • Atualiza desconto ou acrescimo no financeiro e recalcula o valor_total.
   • Registra um lançamento no histórico com forma desconto/acrescimo (não conta como pagamento).
   • Redistribui as parcelas pendentes do plano de pagamento.

Casos especiais

Plano de pagamentos PIX parcelado

Quando a compra foi feita pelo site com PIX parcelado, o sistema gera automaticamente as parcelas (origem = plano_pagamento):

• Sinal+Saldo - duas parcelas: sinal com vencimento hoje (pago no checkout) e saldo com vencimento configurado.
• Plano automático - distribui as parcelas igualmente até 7 dias antes da viagem, respeitando um intervalo mínimo de 3 dias entre parcelas. Se a viagem é iminente, vira parcela única.

Cada parcela aparece no histórico com parcela_numero e fica pendente até o cliente pagar pelo portal ou você dar baixa manualmente via Registrar Pagamento informando o número da parcela.

Estornar um pagamento

Estornar é diferente de reembolsar: estornar corrige um lançamento errado (digitou o valor errado, registrou em forma errada, lançou em duplicidade).

1. Abra Ver Histórico do passageiro.
2. Localize o lançamento e use a ação Estornar disponível no item.
3. Informe o motivo (obrigatório).
4. O lançamento é marcado como estornado (não é apagado, fica auditável) e o valor_pago é recalculado automaticamente.

Reembolsar (devolver dinheiro)

Reembolso é dinheiro saindo do caixa para o cliente - exige conta bancária. Diferente do estorno, o reembolso vira uma despesa real no módulo financeiro.

1. No dropdown de Ações, clique em Reembolsar (aparece apenas se valor_pago - valor_reembolsado > 0).
2. No modal:
   • Valor - não pode ultrapassar o disponível para reembolso.
   • Conta - selecione a conta bancária que vai pagar (de fin_contas).
   • Motivo - obrigatório.
3. Confirme. O VendaFinanceiroSyncService cria uma FinTransacao de despesa na categoria Reembolsos a Clientes, debita a conta e atualiza valor_reembolsado. O reembolso não cancela o passageiro automaticamente - se for o caso, cancele depois pela ação Cancelar.

Dedup de pagamento duplicado

Ao registrar um pagamento idêntico (mesmo financeiro + valor + forma) em menos de 60 segundos, o sistema bloqueia e devolve HTTP 409. A mensagem inclui o ID do pagamento existente. Para forçar (ex: duas cobranças PIX reais idênticas no mesmo dia), marque a opção permitir duplicado ou aguarde 1 minuto.

Assento adicional consolidado

Passageiros marcados como assento adicional (mesma reserva online com financeiro zerado) exibem a mensagem "Assento adicional · financeiro consolidado no passageiro principal" no rodapé do cartão. Toda a movimentação financeira é feita pelo passageiro titular do pedido.

Erros comuns e como resolver

• "Já foi registrado um pagamento idêntico há menos de 1 minuto..." - Causa: dedup de 60s do registrarPagamento. Solução: confirme se não é clique duplo; se for cobrança real diferente, marque permitir duplicado ou aguarde 1 minuto.
• "Este pagamento já foi estornado" - Causa: o lançamento já tem estornado = true. Solução: nada a fazer; o valor já foi desfeito. Use Ver Histórico para confirmar.
• "Passageiro sem financeiro vinculado" - Causa: tentativa de reembolsar antes de qualquer registro financeiro existir. Solução: registre o pagamento primeiro; o financeiro é criado automaticamente no primeiro lançamento.
• "Este passageiro não possui desconto/acréscimo aplicado" - Causa: tentativa de remover sem ter aplicado. Solução: confira em Ver Histórico se o desconto está ativo (não estornado).
• "Passageiro pagou mas não aparece" - Causa comum: pagamento foi registrado em outro pedido/passageiro do mesmo comprador, ou em assento adicional cujo financeiro está consolidado no titular. Solução: abra Ver Histórico do titular do pedido.
• Valor maior que o disponível no reembolso - Causa: o controller valida max = valor_pago - valor_reembolsado. Solução: confira em Ver Histórico quanto já foi reembolsado e ajuste o valor.

Onde encontrar

• URL: /admin/excursoes/{excursao}/passageiros
• Caminho no menu: Excursões > (excursão) > Passageiros
• Permissão necessária: ver as viagens para abrir a página; ver o financeiro para enxergar e usar as ações financeiras (registrar pagamento, desconto, acréscimo, reembolso, ver histórico).
• Módulo necessário: nenhum. As ações de pagamento/estorno/reembolso funcionam mesmo sem o módulo gestão-financeira - o módulo só é exigido para abrir o módulo financeiro completo (contas, transações, relatórios).

Veja também

• Visão Geral dos Passageiros
• Cancelamento e Transferência
• Status do Passageiro
• Cadastrar Passageiro