Contratos - Gerar PDF e Cartão de Embarque

O que é

A tela de contratos da excursão concentra os dois documentos formais que o cliente costuma pedir: o PDF do contrato (com cláusulas, dados do grupo, valores e registro do aceite) e o Cartão de Embarque individual, com QR Code usado no check-in. Ambos são gerados sob demanda pelo Gotenberg (serviço de renderização HTML para PDF) e, em caso de indisponibilidade, caem automaticamente para o renderizador DomPDF.

O administrador normalmente chega aqui depois que o passageiro confirma a reserva, para conferir o conteúdo antes de enviar o link de assinatura, ou às vésperas da viagem, para imprimir/encaminhar o cartão de embarque ao cliente. O PDF é consolidado por comprador: se o titular tem dependentes ou várias reservas na mesma excursão, todos saem em um único contrato.

Como usar

1. Vá em Excursões no sidebar e abra a excursão desejada.
2. Acesse Contratos dentro da excursão (URL /admin/excursoes/{excursao}/contratos).
3. Localize o titular do contrato na lista (cada linha representa um comprador, não um passageiro individual).
4. Clique no menu de três pontos Ações ao final da linha e escolha uma das opções:
   • Baixar PDF - gera o arquivo contrato-{slug-do-cliente}-{qr_code}.pdf e baixa direto no navegador.
   • Cartão de Embarque - gera o cartão individual em PDF do titular do grupo (só aparece se o passageiro estiver apto ao embarque).
5. Para visualizar o PDF antes de baixar, clique em Ver Contrato no dropdown. Na tela de detalhes, o PDF aparece embutido em iframe (coluna direita) usando a rota stream-pdf, com cabeçalho "Contrato em PDF". Os mesmos botões Baixar PDF e Cartão de Embarque ficam visíveis no painel "Ações" à esquerda.

Casos especiais

Contrato consolidado por comprador

Quando o mesmo comprador fez compras separadas ou tem dependentes na mesma excursão, o sistema agrupa todos os passageiros em um único PDF. O representante eleito é o titular real (cliente_id = comprador_id); se o comprador não viaja, o primeiro passageiro do grupo assume o representante. O valor exibido no PDF soma o valor_total das orders distintas do comprador.

Cartão de embarque indisponível

Se o botão Cartão de Embarque estiver substituído por Cartão Indisponível (cinza), o passageiro tem requisitos pendentes. Os requisitos verificados em aptoParaEmbarque() são:

• Aceite do contrato (quando a excursão exige contrato).
• Documentos obrigatórios aprovados pela equipe.
• Pagamento concluído (status do financeiro).

A lista exata de pendências aparece em um quadro amarelo logo abaixo do botão, na tela de detalhes do contrato. Para dependentes, o titular precisa estar apto e o dependente precisa ter os documentos próprios aprovados.

Fallback do Gotenberg

A renderização padrão usa Gotenberg em pdf.gotenberg.contrato e pdf.gotenberg.cartao-embarque. Se o serviço estiver fora do ar, o sistema grava warning no log ("Gotenberg não disponível, usando DomPDF como fallback") e gera o mesmo documento via DomPDF a partir das views pdf.contrato e pdf.cartao-embarque. O resultado visual pode diferir levemente, pois o DomPDF tem suporte CSS reduzido.

Visualização inline vs. download

A rota stream-pdf devolve o PDF com Content-Disposition: inline, usada no iframe da tela de detalhes. Já download-pdf força o download como anexo com nome contrato-{slug-do-cliente}-{qr_code}.pdf.

QR Code do cartão de embarque

O cartão usa o campo qr_code do passageiro. Passageiros legados sem QR Code recebem um código gerado automaticamente no momento da emissão do cartão. A imagem do QR é obtida via API pública e embutida em base64, junto com o logo da sua empresa, garantindo que o PDF funcione offline depois de baixado.

Erros comuns e como resolver

• "404 Not Found" ao tentar baixar - Causa: o passageiro_id não pertence à excursão da URL ($passageiro->excursao_id !== $excursao->id). Solução: reabra o contrato a partir da lista da excursão correta.
• PDF abre em branco no iframe - Causa: Gotenberg indisponível e fallback do DomPDF demorando. Solução: aguardar o spinner "Gerando PDF do Contrato"; se persistir, baixar pelo botão Baixar PDF.
• Botão "Cartão Indisponível" não vira "Cartão de Embarque" - Causa: requisitos de embarque pendentes (contrato, documentos ou pagamento). Solução: verificar o quadro amarelo "Requisitos pendentes" na tela de detalhes do contrato.
• Logo da empresa não aparece no PDF - Causa: empresa sem logo cadastrada ou caminho de arquivo inválido na logo. Solução: enviar a logo em Configurações > Identidade ou ajustar contrato_logo_usar_sistema.

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

Veja também

• Contratos - Gerar e Enviar Links
• Assinatura Digital
• Templates de Contrato
• Variáveis Dinâmicas