Contratos - Editor de Modelo de Contrato

O que é

O editor de modelo de contrato é onde se monta o texto HTML que será reutilizado em várias excursões. Em vez de redigitar cláusulas a cada nova excursão, o modelo guarda o conteúdo formatado e usa placeholders (códigos entre chaves duplas como {{cliente_nome}}) que o sistema substitui automaticamente pelos dados reais do passageiro, da excursão, do embarque e da empresa quando o contrato é gerado.

O usuário costuma chegar nesta página por dois caminhos: ao criar um modelo novo em Módulos > Contratos Digitais > Modelos de Contrato > Novo Modelo de Contrato, ou ao editar um modelo já salvo clicando em um item da listagem. O comportamento da tela é praticamente o mesmo, com a diferença de que o modal Base (carregar modelo pronto) e a geração de PDF só ficam disponíveis em contextos específicos descritos abaixo.

Como usar

1. Vá em Módulos > Contratos Digitais > Modelos de Contrato no sidebar e clique no modelo desejado (ou em Novo Modelo de Contrato para criar um do zero).
2. No bloco Informações do Modelo preencha:
   • Nome (obrigatório) - identifica o modelo na listagem e nos seletores das excursões. Ex: "Contrato Turismo Nacional".
   • Categoria - opção da lista (Eventos, Viagem, Aventura, Religioso, Escolar, Minimalista, Jornada). Serve para agrupar os modelos.
   • Modelo Padrão - marque o checkbox para que este modelo seja usado automaticamente quando uma excursão não tem modelo próprio vinculado. Ao marcar, o sistema desmarca o padrão anterior na hora de salvar.
   • Descrição - texto livre (até 1000 caracteres) que aparece abaixo do nome na listagem.
3. No bloco do editor, escreva ou cole o conteúdo do contrato no TinyMCE. A toolbar tem undo redo | blocks | bold italic forecolor | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | removeformat | link | table | code | fullscreen | help. Use code para editar HTML cru e fullscreen para ampliar a área do editor.
4. Para inserir um placeholder, abra a seção desejada no painel Placeholders à direita (Cliente, Excursão, Embarque, Transporte, Financeiro, Reserva, Sistema, Empresa, Contrato, Dependentes, Guia) e clique no item. O código (ex: {{cliente_nome}}) é inserido na posição do cursor do TinyMCE e aparece um toast confirmando a inserção. Se o editor não estiver disponível, o sistema copia o placeholder para a área de transferência.
5. Confira o resultado antes de salvar:
   • Preview - gera o HTML com dados fictícios e mostra dentro de um modal (banner laranja "PREVIEW DO CONTRATO"). Útil para validar formatação.
   • PDF - abre o PDF de exemplo em nova aba via Gotenberg (com fallback para DomPDF). Disponível apenas após salvar o modelo pela primeira vez; em modelos novos o botão exibe o toast "Salve o modelo primeiro para gerar o preview em PDF.".
   • Dados - abre o modal Dados Fictícios do Preview, com a tabela de cada placeholder e o valor que será injetado. Dados da empresa vêm da sua empresa atual (nome, cnpj, telefone, email, endereco, logo e rodapé), o restante vem de config/contrato-preview.php.
6. Clique em Salvar (botão verde, atalho Ctrl+S). A página recarrega na tela de edição do mesmo modelo com o toast "Modelo de contrato atualizado com sucesso!" (ou "Modelo de contrato criado com sucesso!" no fluxo de criação).

Casos especiais

Carregar um modelo base ao criar do zero

No fluxo de Novo Modelo aparece o botão Base (roxo, à direita de Preview). Ele abre o modal Carregar Modelo Base com cartões coloridos por categoria listados a partir de config/contrato-templates.php. Clicar em um cartão substitui todo o conteúdo do editor pelo HTML pronto e dispara o toast Modelo base "X" carregado!. O botão Base não aparece em modo edição - para reaproveitar um modelo já salvo, use o botão Duplicar na listagem.

Trocar o modelo padrão

Marcar Modelo Padrão num modelo enquanto outro já estava marcado funciona como "transferência": ao salvar, o método update desmarca is_padrao de todos os outros dentro da mesma transação. Não é preciso editar o padrão antigo manualmente.

Modelo está vinculado a excursões

Quando o usuário tenta excluir pela listagem um modelo já vinculado a excursões, o sistema não apaga - apenas marca como inativo (ativo = false) e mostra o toast "Modelo desativado. Está vinculado a X excursão(ões).". Os contratos já gerados continuam válidos. O modelo padrão também não pode ser excluído (mensagem "Não é possível excluir o modelo padrão."). Para retirar um modelo padrão de circulação, primeiro defina outro como padrão.

Logo, rodapé e assinatura da empresa

Logo e rodapé só aparecem no PDF se estiverem configurados na sua empresa (Contratos Digitais > Configurações). O sistema usa o logo principal da empresa quando contrato_logo_usar_sistema está ativo; caso contrário, usa o logo específico do contrato (contrato_logo). O rodapé só renderiza se contrato_rodape_ativo estiver marcado e contrato_rodape preenchido. O placeholder {{empresa_assinatura}} é substituído pela imagem real configurada em contrato_assinatura_empresa.

Limite de tamanho do conteúdo

A validação aceita até 100.000 caracteres no campo conteudo. Acima disso o formulário falha com a mensagem padrão de validação do Laravel. Para contratos muito longos, considere dividir em modelos por tipo de excursão.

Erros comuns e como resolver

• "O campo nome é obrigatório." - Causa: o campo Nome ficou vazio. Solução: preencha o nome do modelo antes de salvar.
• "O campo conteúdo é obrigatório." - Causa: o editor TinyMCE está vazio (acontece principalmente após carregar uma base e limpar tudo). Solução: digite ou cole pelo menos um trecho no editor antes de salvar.
• "Salve o modelo primeiro para gerar o preview em PDF." - Causa: o botão PDF foi clicado num modelo ainda não salvo. Solução: clique em Salvar primeiro; o sistema redireciona para a tela de edição e habilita o PDF.
• "Não é possível excluir o modelo padrão." - Causa: tentativa de excluir o modelo marcado como padrão. Solução: marque outro modelo como Modelo Padrão primeiro; depois volte e exclua o anterior.
• Placeholder aparece literal no PDF (ex: {{cliente_nome}} no lugar do nome)
  • Causa: o código foi digitado com formatação diferente do dicionário (espaços, acento, chaves erradas). Solução: apague e reinsira clicando no painel Placeholders para garantir a sintaxe exata. Consulte a lista completa em Variáveis Dinâmicas.

Onde encontrar

• URL: /admin/contratos/templates/{template}/edit
• Caminho no menu: Módulos > Contratos Digitais > Modelos de Contrato > (clicar num modelo)
• Permissão necessária: gerenciar modelos de contrato
• Módulo necessário: Contratos Digitais (contratos-digitais)

Veja também

• Modelos de Contrato (listagem)
• Variáveis Dinâmicas
• Configurações de Contratos
• Contratos Digitais - Módulo Adicional