Contratos - Assinatura Digital

O que é

A assinatura digital e o fluxo que o passageiro percorre para formalizar eletronicamente o contrato da excursão, sem precisar imprimir, assinar a caneta ou devolver papel. Ele acontece no subdominio publico assinatura.viagilize.com.br, fora do painel administrativo, e e ativado quando o módulo Contratos Digitais esta habilitado para o empresa.

O cliente normalmente chega aqui de duas formas: clicando no link recebido por e-mail/WhatsApp logo após a reserva (parametro ?from=email ou envio manual pelo administrador) ou entrando pelo Minha Conta no portal do cliente (parametro ?from=portal). Cada link e único por passageiro, gerado a partir do access_token do registro SignatureAgreement, e percorre quatro etapas sequenciais: verificar identidade, confirmar dados, ler o documento e desenhar a rubrica.

Como usar

O fluxo abaixo descreve a experiência do passageiro. O administrador acompanha o status pelo modulo de Contratos Digitais e pode reenviar o link a qualquer momento.

1. O passageiro abre o link de assinatura recebido por e-mail ou WhatsApp. A página apresenta a barra de progresso com tres etapas: Verificar, Confirmar e Assinar.
2. Na tela Verificar Identidade, o sistema envia automaticamente um código de 6 caracteres alfanumericos para o e-mail cadastrado. O passageiro digita o código no campo central e confirma. Caso o link tenha vindo do proprio e-mail (?from=email), esta etapa e pulada automaticamente porque a posse do link ja comprova a identidade.
3. Se o código não chegar, clicar em Reenviar código dispara um novo envio para o mesmo e-mail e zera o contador de tentativas. Em alternativa, e possível escolher Receber por WhatsApp/SMS, que usa a Evolution API e, em caso de falha, o AWS SNS como fallback.
4. Na tela Confirmar Dados, o passageiro confere ou completa o Nome completo, CPF e Telefone. Campos ja cadastrados pelo admin aparecem preenchidos e travados; ao informar um CPF que diverge do cadastrado, o sistema bloqueia o avanco. Quando o cliente informa CPF ou celular pela primeira vez, esses dados são sincronizados automaticamente no cadastro do cliente na sua empresa.
5. Na tela Documento, o contrato e exibido com o visualizador de PDF embutido. O botao Baixar PDF abre o original em nova aba e o acesso e registrado como evento de visualizacao na timeline do acordo.
6. Após rolar o documento, o passageiro clica em Aceitar e Assinar para abrir a tela Assine o Documento. Ele desenha a rubrica no canvas (mouse, trackpad ou dedo na tela touch) e, se errar, usa o icone de lixeira para limpar e refazer.
7. O passageiro marca a caixa Declaro que li e concordo com o conteudo do documento e clica em Confirmar Assinatura. O sistema:
   • salva a imagem PNG da rubrica no storage configurado (contratos.assinatura.storage_disk);
   • gera um hash SHA-256 unindo a rubrica, o timestamp e o ID do acordo;
   • chama o SignedDocumentService, que monta o PDF assinado final com rodape de validação em todas as páginas e certificado de assinatura ao final;
   • atualiza o passageiro na sua empresa com aceite_status = true, aceite_data, aceite_ip e aceite_user_agent;
   • envia o e-mail AssinaturaConfirmadaMail com a copia anexada.
8. A tela Documento Assinado com Sucesso confirma a operação, mostra os detalhes da assinatura (nome do signatario, data/hora, hash) e oferece o botao Baixar copia assinada alem do atalho para Meus Documentos.

Casos especiais

Cliente acessa o link depois de ja ter assinado

Quando o link e aberto novamente após o aceite, o sistema redireciona para a tela Ja Assinado, que exibe data, IP da assinatura e um botao publico para baixar a copia, sem exigir nova autenticacao. Isso evita a mensagem confusa de "Link invalido" no segundo acesso.

Verificacao por WhatsApp ou SMS

Quando o passageiro não consegue acessar o e-mail, a tela de código oferece o envio por celular. O sistema tenta primeiro o WhatsApp via Evolution API (instancia viagilize-crm por padrão). Se a instancia estiver desconectada, faz fallback para SMS via AWS SNS. O código enviado e o mesmo que iria por e-mail (ou um novo, se o anterior tiver expirado), com validade de 7 dias.

Código expirado ou máximo de tentativas excedido

Por padrão o código expira em 1440 minutos (configuravel via contratos.assinatura.codigo_expira_minutos) e o limite e de 5 tentativas (contratos.assinatura.max_tentativas_codigo). Após estourar qualquer um dos dois, o campo bloqueia e o passageiro precisa clicar em Reenviar código, que gera um novo código e zera as tentativas.

Recusar o contrato

Abaixo do botao Aceitar e Assinar existe a opção Recusar contrato. O passageiro precisa escrever um motivo entre 10 e 1000 caracteres, e o acordo passa para status refused. A partir desse ponto, o link não aceita mais assinatura e o admin recebe o registro para acionamento manual.

Cliente vindo do portal "Minha Conta"

Quando o link traz ?from=portal, o sistema guarda na sessão a URL de retorno do portal da sua empresa (/minha-conta/dashboard). Após assinar, a tela de sucesso oferece o caminho de volta para o portal alem do Meus Documentos publico.

Contrato unifica varias compras do mesmo comprador

Se o comprador fez mais de uma compra na mesma excursão, o contrato gerado consolida todas as orders e lista todos os dependentes em um único documento. O valor exibido e a soma de Order.valor_total das orders distintas do comprador.

Erros comuns e como resolver

• "Código invalido. Você tem X tentativa(s) restante(s)." - Causa: o código digitado não confere com o enviado. Solucao: conferir maiusculas e minusculas (o sistema converte para maiusculas automaticamente) e evitar espacos colados; em último caso, clicar em Reenviar código.
• "Seu código expirou. Clique em 'Reenviar código' para receber um novo." - Causa: o código passou da janela configurada em codigo_expira_minutos. Solucao: clicar em Reenviar código ou em Receber por WhatsApp/SMS.
• "Número máximo de tentativas excedido. Clique em 'Reenviar código' para receber um novo." - Causa: 5 tentativas erradas seguidas. Solucao: pedir novo código, o que zera o contador.
• "O CPF informado não confere com o cadastrado." - Causa: o admin ja registrou o CPF do passageiro na sua empresa e o número digitado e diferente. Solucao: o cliente deve digitar o CPF correto; se houver erro no cadastro, o admin precisa corrigir no perfil do passageiro antes do cliente prosseguir.
• "Link invalido ou expirado." - Causa: o access_token não foi encontrado, foi substituido por uma nova versão do contrato (superseded_at preenchido) ou o acordo expirou. Solucao: o admin precisa gerar e enviar um novo link a partir do modulo Contratos.
• "Este contrato foi recusado em DD/MM/AAAA HH:MM." - Causa: o passageiro ja recusou o contrato anteriormente. Solucao: o admin precisa entender o motivo registrado e, se for o caso, emitir um novo acordo.
• "Não foi possível enviar o código. Tente novamente." (envio por celular) - Causa: a instancia do WhatsApp esta desconectada e o AWS SNS também falhou. Solucao: usar o código por e-mail ou pedir para o suporte verificar o status da Evolution API.
• "Erro ao processar assinatura. Documento original não encontrado."
  • Causa: o PDF original foi removido do storage entre a geracao do link e o momento da assinatura. Solucao: o admin precisa reemitir o link, o que gera novamente o PDF.

Onde encontrar

• URL canonica do passageiro: https://assinatura.viagilize.com.br/d/{token}
• Area do signatario após autenticado: https://assinatura.viagilize.com.br/meus-documentos
• Verificador publico por hash: https://assinatura.viagilize.com.br/verificar/{hash}
• Caminho no menu admin (acompanhamento): Contratos Digitais > Contratos
• Permissão necessária: ver os contratos
• Módulo necessário: contratos-digitais
• Layout: páginas publicas servidas pelo subdominio assinatura, registradas em routes/system-subdomains.php (rotas assinatura.*)

Veja também

• Templates de Contrato - ajustar o texto do contrato e variaveis dinamicas antes do envio
• Gerar e Enviar Links - como o administrador dispara o link de assinatura para o passageiro