Contratos - Contratos da Excursão

O que é

A página Contratos da excursão consolida, em uma única lista, todos os contratos digitais ligados àquela viagem. Cada linha representa um titular (comprador principal) que assina o contrato por todo o seu grupo - dependentes e convidados ficam vinculados ao mesmo contrato e não aparecem em linhas separadas. Quando o mesmo comprador fez mais de uma compra (orders distintas) para a mesma excursão, o sistema unifica tudo em um único contrato, somando o valor total e listando os códigos das reservas.

Esta é a tela usada no dia a dia operacional para responder rapidamente "quem ainda não assinou?", reenviar o link de assinatura para pendentes, baixar o PDF do contrato e - quando o titular está apto - emitir o cartão de embarque. O cabeçalho mostra um resumo em quatro cartões: Total Passageiros, Contratos (Grupos), Aceitos e Pendentes.

Como usar

1. Vá em Excursões no sidebar e abra a excursão desejada.
2. Dentro da página de edição, acesse a aba/link Contratos (URL /admin/excursoes/{excursao}/contratos).
3. Confira o painel de estatísticas no topo:
   • Total Passageiros - quantidade de passageiros confirmados/pendentes na excursão.
   • Contratos (Grupos) - número de contratos consolidados (um por titular/comprador).
   • Aceitos - quantos titulares já aceitaram.
   • Pendentes - diferença entre grupos e aceitos.
4. Percorra a lista de titulares. Cada linha traz o avatar do cliente, nome, CPF, código da reserva, data/hora de aceite (quando houver), quantidade de passageiros do grupo e o valor total somado.
5. Use o badge de status para filtrar visualmente:
   • Aceito (verde) - contrato assinado, exibe a label da versão.
   • Pendente (amarelo) - ainda não há aceite registrado.
   • Reaceite necessário (laranja) - o grupo mudou após a assinatura e uma nova versão precisa ser aceita.
   • Com Assinatura Eletrônica ativa, aparecem ainda os status Assinado, Aguardando assinatura, Recusado, Cancelado e Nova versão necessária.
6. No dropdown de ações (ícone à direita da linha) escolha:
   • Ver Contrato - abre a página de detalhes do contrato do titular.
   • Copiar Link - gera e copia o link de assinatura para a área de transferência (toast confirma "Link copiado para a área de transferência!").
   • Baixar PDF - faz o download do contrato em PDF.
   • Cartão de Embarque - aparece somente quando o titular está apto para embarque.
7. Para ver todos os aceites e versões já registradas, clique em Histórico de Aceites no cabeçalho.
8. Para editar o conteúdo do modelo aplicado a esta excursão, clique em Editar Template no cabeçalho.

Casos especiais

Excursão sem contratos cadastrados

Quando nenhum passageiro confirmado/pendente é encontrado, a lista exibe o estado vazio com a mensagem "Nenhum contrato encontrado para esta excursão." Cadastre passageiros na excursão para que os contratos apareçam aqui.

Comprador com mais de uma reserva na mesma excursão

O sistema agrupa todas as orders do mesmo comprador_id em um único contrato. O valor exibido é a soma dos valor_total das reservas distintas e a quantidade de passageiros considera o grupo inteiro (titular + dependentes + convidados confirmados).

Assinatura Eletrônica habilitada

Se você usa o módulo de Assinatura Eletrônica, aparece um banner roxo logo abaixo das estatísticas avisando que os contratos serão assinados eletronicamente com validade jurídica. Os status passam a refletir o ciclo do SignatureAgreement (assinado / aguardando / recusado / cancelado / nova versão necessária) em vez do simples aceite_status.

Contrato invalidado por mudança no grupo

Quando o grupo do titular muda após o aceite (entrada/saída de dependentes, troca de embarque, etc.), o contrato anterior é invalidado e o badge passa a Reaceite necessário (laranja). Reenvie o link para o titular renovar a assinatura.

Convites pendentes e dependentes

Passageiros com cadastrado_via igual a convite_pendente, link_convite ou link_convite_dependente, e também passageiros que são dependentes de outro titular, não geram linha própria - eles entram no contrato do respectivo titular.

Erros comuns e como resolver

• "Erro ao gerar link: ..." (toast vermelho ao clicar em Copiar Link) - Causa: o titular não está mais elegível (status do passageiro alterado) ou o serviço de assinatura retornou erro. Solução: recarregue a página, abra Ver Contrato e gere o link a partir da tela de detalhes.
• "Erro ao gerar link do contrato." (toast vermelho genérico) - Causa: falha de rede ao chamar o endpoint gerar-link. Solução: tente novamente; persistindo, verifique a conexão e o status do servidor.
• Cartão de Embarque não aparece no dropdown - Causa: o titular ainda não está apto para embarque (faltam documentos, pagamento ou ficha médica, conforme regra de aptoParaEmbarque()). Solução: regularize as pendências do passageiro antes de tentar emitir o cartão.
• Página retorna 404 ao abrir um contrato específico - Causa: o passageiro informado na URL não pertence a esta excursão. Solução: volte para a lista e acesse o contrato pelo botão Ver Contrato do titular.

Onde encontrar

• URL: /admin/excursoes/{excursao}/contratos
• Caminho no menu: Excursões > (abrir excursão) > Contratos
• Permissão necessária: ver as viagens
• Módulo necessário: Contratos Digitais (contratos-digitais)

Veja também

• Templates de Contrato
• Configurar Template de Contrato
• Gerar e Enviar Links
• PDF e Cartão de Embarque
• Assinatura Digital
• Contratos Digitais - Módulo Adicional