Reservas - Pagamentos da Reserva

O que é

A área de pagamentos concentra todo o controle financeiro de uma reserva individual na tela de detalhes do passageiro ("/admin/reservas/{passageiro}"). Ela mostra o card Financeiro com valor total, pago e pendente, a seção Plano de Pagamentos com o histórico de pagamentos confirmados e parcelas agendadas, e exibe os botões para registrar pagamento manual, configurar um plano parcelado, aprovar pagamentos que chegaram via meio de pagamento, editar/excluir lançamentos manuais e baixar o recibo em PDF.

O atendente normalmente chega aqui depois que o cliente avisa que pagou fora do sistema (PIX direto, dinheiro, transferência, cheque), quando precisa quebrar o saldo em parcelas com vencimentos futuros, ou quando o meio de pagamento processou um pagamento que exige aprovação manual antes de confirmar a reserva. Toda movimentação ajusta automaticamente o valor pago e o status do financeiro, podendo confirmar o passageiro quando o saldo fica zerado.

Como usar

Registrar um pagamento manual

1. Vá em Reservas no sidebar e abra a reserva desejada em /admin/reservas/{passageiro}.
2. No card Financeiro (coluna direita), clique em Registrar Pagamento (botão verde com ícone de mais).
3. No modal Registrar Pagamento, preencha:
   • Valor - obrigatório, no formato brasileiro (1.234,56). Aceita pagamento parcial em relação à parcela selecionada.
   • Forma de Pagamento - obrigatório. Opções: PIX, Dinheiro, Transferência, Cartão de Crédito, Cartão de Débito, Boleto, Cheque.
   • Data do Pagamento - obrigatório.
   • Observação - opcional, até 500 caracteres.
4. Clique em Registrar Pagamento (botão verde no rodapé do modal). O sistema exibe o toast "Pagamento registrado com sucesso!" e atualiza o valor pago, o valor pendente e o status do financeiro.

Configurar um plano de pagamentos parcelado

1. Na tela de detalhes da reserva, no card Financeiro, clique em Agendar Pagamentos (botão cinza com ícone de engrenagem). O botão só aparece quando há valor pendente e a reserva não está cancelada.
2. No modal Configurar Plano de Pagamento:
   • Use Ações Rápidas (1x até 10x) para dividir o valor pendente automaticamente, ou clique em Adicionar Parcela para montar parcela a parcela.
   • Escolha o Intervalo entre parcelas: 30 dias (a partir de hoje) ou Mesmo dia (mesmo dia do mês, mensalmente).
   • Para cada parcela, ajuste Valor, Forma (PIX, Boleto, Dinheiro, Transferência, Crédito, Débito, Link Pgto, Cheque) e Vencimento (calendário com data mínima sequencial).
3. Confira o Total das Parcelas no resumo do rodapé do modal: ele precisa ser exatamente igual ao Valor Pendente para que o botão Salvar Plano fique habilitado.
4. Clique em Salvar Plano. As parcelas são criadas como pagamentos com status Pendente e aparecem na seção Plano de Pagamentos da própria reserva.

Aprovar um pagamento aguardando confirmação

1. Acesse /admin/reservas/pagamentos-aguardando (atalho a partir do menu Reservas) para ver a lista global de pagamentos aguardando aprovação manual recebidos via meio de pagamento.
2. Alternativamente, abra a reserva específica: na seção Plano de Pagamentos, o pagamento aparece com etiqueta Aguardando Confirmação e um botão verde Confirmar.
3. Clique em Confirmar. O sistema chama confirmarManualmente(), atualiza o valor pago, sincroniza o financeiro e, se o saldo zerar, confirma o passageiro. Toast: "Pagamento confirmado com sucesso! A reserva foi atualizada."

Baixar o recibo em PDF

1. Na seção Plano de Pagamentos da reserva, identifique o pagamento desejado (precisa estar Confirmado e não estornado).
2. Clique no botão de compartilhar/recibo no canto direito do card do pagamento. O PDF é gerado pelo ReciboPagamentoService e aberto inline no navegador (recibo-pagamento-{id}.pdf).

Editar ou excluir um pagamento manual

1. Localize o pagamento na seção Plano de Pagamentos.
2. Clique em Editar (botão azul) para alterar Valor, Forma, Data do Pagamento e Observação. Confirme em Salvar Alterações.
3. Clique em Excluir (botão vermelho) e confirme no modal de exclusão. O valor é removido do saldo pago e o financeiro é recalculado.

Casos especiais

Pagamento parcial de uma parcela agendada

Ao registrar pagamento com Valor menor que o valor da parcela selecionada, o modal mostra o aviso "Pagamento parcial detectado" com o saldo restante e um campo Nova data de vencimento do saldo. O sistema cria um novo registro confirmado com o valor recebido e atualiza a parcela original com o saldo restante e a nova data de vencimento informada. Útil quando o cliente paga apenas parte de uma parcela e combina nova data para o resto.

Pagamento maior que o valor da parcela

Se o Valor informado for maior que o valor da parcela agendada, a parcela é marcada como confirmada com o valor maior (o excedente é absorvido como pagamento da parcela). Não cria parcela nova.

Origem PIX direto

Quando a Forma de Pagamento é PIX, o sistema marca a origem do pagamento como pix_direto; nas demais formas, marca como manual. Pagamentos vindos do meio de pagamento têm origem própria (mercadopago, asaas, pagarme, infinitepay) e não podem ser editados nem excluídos pelo admin - só pagamentos manuais confirmados aceitam edição/exclusão.

Substituir parcelas pendentes ao montar novo plano

Ao salvar um novo plano, marque Substituir Pendentes (campo substituir_pendentes) para que o sistema apague antes os pagamentos em status Pendente sem data de pagamento. Pagamentos Confirmados nunca são removidos por essa operação.

Total das parcelas precisa bater com o valor pendente

A diferença permitida é de R$ 0,01. Se o total das parcelas ficar acima ou abaixo do valor pendente, o sistema rejeita com a mensagem "O total das parcelas (R$ X) deve ser igual ao valor pendente (R$ Y)". Para passageiro titular de grupo (titular com order_id), o valor pendente considerado é o do pedido inteiro, agregando todos os passageiros do grupo - mesmo critério usado no card Financeiro.

Quitação total confirma a reserva e dispara convites

Quando o pagamento zera o saldo, o status do financeiro passa para Pago e o passageiro pendente é automaticamente movido para Confirmado. Se o pedido tem convites pendentes (ExcursaoPassageiroPendente em aguardando_pagamento) e a excursão está Publicada, o sistema envia os convites pendentes na mesma operação.

Rejeitar um pagamento aguardando confirmação

Ainda dentro da fila de aprovação, é possível rejeitar um pagamento informando o Motivo (obrigatório, até 500 caracteres). O pagamento fica com status Cancelado e o motivo é adicionado ao campo Observação com prefixo "Rejeitado: ...". A reserva não muda de status pelo simples ato de rejeitar.

Remover uma parcela agendada

Parcelas com status Pendente que ainda têm vencimento futuro podem ser removidas individualmente pela rota admin.reservas.plano-pagamento.destroy (acionada pelo botão de lixeira dentro do plano). Parcelas já Confirmadas ou sem data de vencimento não podem ser removidas por essa rota.

Reserva com pedido misto (excursão + ingresso + experiência)

Quando o pedido inclui ingressos ou experiências/passeios além da excursão, o card Financeiro desta tela mostra apenas o financeiro da excursão. Os valores de ingressos vivem em /admin/ingressos/vendas e os de experiências em /admin/passeios/vendas - um aviso amarelo no topo do card aponta para a tela correspondente.

Erros comuns e como resolver

• "Este pagamento não está aguardando confirmação." - Causa: tentativa de confirmar um pagamento que já foi confirmado, cancelado ou estornado. Solução: recarregue a tela; se o pagamento já está confirmado, nada mais precisa ser feito.
• "Este pagamento não pode ser editado." ou "Este pagamento não pode ser excluído." - Causa: o pagamento é de meio de pagamento (não manual), já foi estornado, ou não está confirmado. Solução: a edição/exclusão só vale para pagamentos manuais confirmados; para meio de pagamento, faça estorno na tela do próprio meio de pagamento/financeiro.
• "O total das parcelas (R$ X,XX) deve ser igual ao valor pendente (R$ Y,YY)." - Causa: soma das parcelas no plano não bate com o saldo pendente. Solução: ajuste valores ou use a ação rápida (1x até 10x) para dividir automaticamente.
• "Apenas parcelas pendentes agendadas podem ser removidas." - Causa: tentativa de remover parcela já confirmada ou sem data de vencimento. Solução: se já foi confirmada, use Excluir no card do pagamento (regra de manual confirmado se aplica).
• "Registro financeiro não encontrado." - Causa: a reserva não tem ExcursaoPassageiroFinanceiro vinculado (caso raro, em geral reservas antigas migradas). Solução: abra chamado para o suporte recriar o financeiro antes de registrar pagamentos.
• "Recibo disponível apenas para pagamentos confirmados." - Causa: tentativa de baixar recibo de pagamento pendente, aguardando aprovação ou cancelado. Solução: confirme o pagamento primeiro.
• "Erro ao gerar o recibo. Tente novamente." - Causa: falha temporária do gerador de PDF (Gotenberg/DomPDF). Solução: aguarde e repita; se persistir, registre o ID do pagamento e abra suporte.
• "Este pagamento não pode ser rejeitado." - Causa: tentativa de rejeitar pagamento que não está em Aguardando Confirmação. Solução: confira o status atual; se já foi confirmado, cancele manualmente a reserva caso seja preciso reverter.

Onde encontrar

• URL: /admin/reservas/{passageiro} (operação por reserva) e /admin/reservas/pagamentos-aguardando (fila global de aprovação manual)
• Caminho no menu: Reservas (item fixo do sidebar)
• Permissão necessária: ver as reservas para visualizar; editar as reservas para registrar, editar, excluir, confirmar, rejeitar pagamentos e configurar plano de pagamento
• Módulo necessário: nenhum (faz parte do núcleo de Reservas)

Veja também

• Detalhes da Reserva
• Confirmar Reserva
• Cancelar Reserva
• Status da Reserva
• Lista de Reservas