Contratos e assinatura

Objetivo

O Contrato é o instrumento que formaliza o que o Cliente comprou. Ele sai da versão aceita de uma Proposta — a do lead de origem ou a de uma oportunidade de upsell/renovação do cliente — pelo Contract Builder: um modelo determinístico que o código preenche com os valores da proposta e com as regras contratuais do perfil da organização, mais um trecho curto escrito pela IA e validado. Cada mudança de texto vira uma nova versão com hash SHA-256 e pode ser baixada em PDF. A assinatura acontece no próprio Radar (assinatura Radar, sem custo por documento) ou, se a organização escolher, pela Clicksign. Aditivos de mudança de escopo usam o mesmo fluxo. Este documento cobre geração, revisão, envio, assinatura, cancelamento e a configuração da contratada. O que acontece depois da assinatura (o Escopo) está em funcional/escopos; a conversão do lead em Cliente, em funcional/clientes.

Fluxo

O Consultor converte o lead em Cliente (/radar/lead/:id/converter). Se o Cliente é novo, a Radhr AI gera o contrato em rascunho na mesma hora; se a empresa já era cliente, nada é gerado automaticamente. Quando o cliente aceita na página pública /pp/<código> uma proposta de oportunidade (upsell ou renovação), o contrato daquela versão nasce em rascunho sozinho (só o modelo, sem IA), com título "Contrato de expansão" ou "Renovação", e a oportunidade vai a contrato. O mesmo acontece quando o Consultor registra o aceite no editor da oportunidade (status aceita, ex.: "de acordo" por e-mail): o contrato da versão enviada nasce e a Radhr AI abre a página dele.
Sem contrato automático (ou para gerar outro), o Consultor usa o botão "Gerar contrato da proposta aceita" na aba Contratos e propostas do Cliente 360, com a opção "só o modelo, sem IA".
O Contract Builder monta o texto: cabeçalho, considerandos da IA (opcional), as 14 cláusulas do modelo, a cláusula "Condições específicas da CONTRATADA" quando o perfil da organização a define e até 3 cláusulas específicas da IA. O código valida e grava a v1 com o hash do texto.
O Consultor revisa em /radar/contrato/:id: completa dados entre colchetes (CNPJ, endereço, representante), ajusta datas de início e fim e o tipo de renovação, edita o texto ou regenera com IA. Cada ação salva uma nova versão.
Enviar para assinatura (modo Radar): a Radhr AI cria um link único por signatário (contratante e contratada), manda os e-mails e move o contrato para enviado. No modo Clicksign, o Worker gera o PDF da versão, sobe o documento na Clicksign e ela manda os e-mails (passo 10).
O signatário abre /c/<token>: a primeira abertura registra a visualização (IP e navegador) e o contrato passa a visualizado.
Ele pede o código de 6 dígitos por e-mail, marca "Li o documento inteiro e concordo" e assina.
Quando todas as assinaturas da versão atual estão feitas, o contrato fica assinado, a Oportunidade de origem avança até ganha e todos recebem o e-mail com o certificado de conclusão.
A assinatura dispara a cadeia assinado: o agente escopo roda primeiro — num contrato principal, o Scope Builder gera o Escopo (se ainda não existir); num aditivo, a mudança de escopo correspondente é aplicada — e depois o Organization Auditor (auditoria) relê o perfil da organização com o contrato novo como evidência.
Clicksign: cada assinatura feita lá chega pelo webhook; no fechamento do documento (auto_close) o contrato fica assinado e segue o passo 9.

Regras de negócio

O contrato só nasce de proposta aceita. Exige empresa, proposta com status aceita e versão com itens; sem isso a geração recusa com o motivo. Pelo Cliente 360, a proposta é a do lead de origem; no aceite de uma proposta de oportunidade, é a versão aceita dela (versaoId), e a geração recusa se a proposta da oportunidade ainda não foi aceita. Vive em src/contratos.ts (contextoDoCliente, gerarContrato) e src/proposta-formal.ts.
Um contrato por versão aceita, preso a ela. O contrato guarda a versão da proposta de onde nasceu (proposta_versao_id). Regenerar, editar e criar aditivo leem essa versão, não uma versão aceita mais nova. Gerar um segundo contrato principal da mesma versão é recusado, com orientação para registrar uma mudança de escopo, que vira aditivo. O banco garante isso com um índice único parcial (migração 0023), e duas gerações simultâneas não passam as duas.
Upsell e renovação têm contrato próprio. A proposta pode nascer de uma oportunidade de cliente (migração 0028); a versão aceita dela gera um contrato principal ligado à oportunidade. Proposta aceita de upsell/renovação ainda sem contrato aparece no bloco Contratos do 360 com o botão "Gerar contrato · <título>" (propostasSemContrato). A versão precisa ser de uma proposta do próprio cliente — do lead de origem ou de uma oportunidade dele; outra é recusada. Mudança de escopo de um contrato que já existe continua sendo aditivo. Vive em src/contratos.ts (contextoDoCliente, propostasSemContrato) e src/radar/proposta.ts.
Todo valor vem da proposta. Total da versão, parcelamento (padrão 10x), valor à vista com o desconto das condições, parcelas e recorrentes mensais (fora do total) são preenchidos pelo código. Vive em src/contrato-modelo.ts (montarContrato).
Regras contratuais do perfil da organização. Quando o perfil de IA vigente define regras de contrato ou exclusões, o modelo usa: os dias de suporte (no lugar de 90), as exclusões padrão da cláusula de escopo, o foro (se a contratada não tem um nas configurações) e a cláusula "Condições específicas da CONTRATADA" (garantias, multas, cancelamento, cláusulas obrigatórias da política). Valores em R$ dessas regras viram "[valor conforme a política da CONTRATADA]", porque o validador só aceita valores da proposta. Sem perfil, vale o texto padrão. Vive em src/perfil/condicoes.ts (regrasContratuaisDaOrganizacao) e src/contrato-modelo.ts.
Título por organização. "Contrato de Prestação de Serviços de Consultoria em Resultados Digitais" só quando a contratada é a Witbiz (ou não tem razão social); outra organização tem "Contrato de Prestação de Serviços". Vive em src/contrato-modelo.ts.
A IA escreve só texto. Considerandos (2 a 4 frases) e até 3 cláusulas específicas do cliente, como redatora da própria organização (identidade e bloco do perfil no prompt). Qualquer trecho com R$ que não exista na proposta ou com percentual é descartado; se a IA falhar, o contrato sai só do modelo, com aviso. Vive em src/contratos.ts (adaptarComIA, valoresPermitidos).
Validação antes de gravar. As 14 cláusulas obrigatórias (partes, objeto, escopo, prazo, preço, obrigações da contratada e da contratante, suporte, terceiros, propriedade, confidencialidade, vigência, assinatura, foro) precisam estar presentes e nenhum R$ pode ficar fora da proposta; senão o contrato não é gerado nem regenerado. Vive em src/contratos.ts (validarContrato).
Edição manual também é validada. O texto salvo pelo Consultor precisa:
ter ao menos 200 caracteres e ser diferente da versão atual;
não trazer R$ fora da proposta aceita, nem valor que não estava na versão atual (o que cobre os valores do aditivo);
no contrato principal, manter as cláusulas obrigatórias, reconhecidas pelo título ## n. Título.

Havendo problema, a versão não é gravada e o motivo aparece na tela. Vive em src/contratos.ts (editarContrato).

Versões com hash. Gerar, regenerar, editar e salvar datas criam uma nova versão numerada com o hash SHA-256 do texto e quem gerou (contract-builder ou o login). Vive em src/contratos.ts.
Assinado ou cancelado não muda mais. Edição, regeneração e envio são recusados nesses estados. Vive em src/contratos.ts e src/assinatura.ts.
**Estados pela máquina contrato:** rascunho → enviado → visualizado → assinado | cancelado; enviado e visualizado podem voltar a rascunho. A tela não oferece "assinado" à mão: ele só vem das assinaturas (ou do webhook da Clicksign). Vive em src/estados.ts.
Signatários. Contratante: o contato cujo e-mail é o do lead (senão o primeiro com e-mail). Contratada: o Consultor dono do Cliente, pelo e-mail dele. Se o dono não tem e-mail ou tem o mesmo do contato, só a contratante assina. Sem e-mail do contato, o envio é recusado. Vive em src/assinatura.ts (enviarParaAssinatura).
Nova versão invalida os links antigos. Ao reenviar depois de mudar o texto, as assinaturas pendentes da versão anterior são canceladas e nascem links novos da versão atual. Vive em src/assinatura.ts.
Código de assinatura: 6 dígitos, válido por 15 minutos, só o hash fica no banco, até 5 tentativas; a caixa "Li o documento" é obrigatória. Vive em src/assinatura.ts (enviarCodigo, assinar).
Prova da assinatura. Cada assinatura grava instante, IP, navegador e um hash que combina o hash da versão, o papel, o e-mail, o instante e o IP. O certificado lista a trilha completa. Vive em src/assinatura.ts.
Sem e-mail configurado, os links aparecem na tela do contrato para envio manual. Vive em src/assinatura.ts (radarProvedor).
Aditivo. Contrato tipo = aditivo ligado ao principal (contrato_pai_id), numerado, com só o delta da mudança (objeto, preço, prazo) e ratificação do resto. Nasce em rascunho da aprovação de uma Mudança de escopo e segue o mesmo envio e assinatura. Só se faz aditivo de contrato principal não cancelado. Vive em src/contratos.ts (criarAditivo) e src/contrato-modelo.ts (montarAditivo).
PDF gerado no Worker. src/pdf.ts gera o PDF sem dependências (A4, Helvetica com acentos, títulos, listas, tabelas simples, rodapé com código, versão, hash e "Página X de Y"), a partir do markdown da versão atual. O mesmo arquivo serve ao download (GET /radar/contrato/:id/pdf) e à Clicksign (pdfDoContrato em src/clicksign.ts).
Provedor gravado no nascimento. O contrato guarda o modo de assinatura da organização no dia em que nasceu; mudar a configuração depois não troca o provedor de um contrato que já existe. O aditivo herda o provedor do principal.
Clicksign de ponta a ponta. Com o modo clicksign e o segredo CLICKSIGN_TOKEN, "Enviar para assinatura" sobe o PDF pela API v1 (documento em base64, prazo de 30 dias, fechamento automático, lembrete a cada 3 dias), cria um signatário por assinatura (autenticação por e-mail; cliente assina como contratante, a organização como contratada) e os vincula ao documento; a Clicksign manda os e-mails e cobra. A key do documento fica em contratos.provedor_ref. Se nenhum signatário for vinculado, o documento é cancelado lá e o envio falha. Cancelar o contrato na Radhr AI cancela o documento na Clicksign. CLICKSIGN_BASE_URL aponta para o sandbox (padrão: https://app.clicksign.com). Vive em src/clicksign.ts.
Webhook da Clicksign (/api/webhooks/clicksign) valida o HMAC com CLICKSIGN_WEBHOOK_SECRET, acha o contrato em qualquer organização e roda na dele: sign grava o evento assinatura_registrada, auto_close marca assinado e dispara a cadeia assinado (só quem fez a transição: webhook repetido não dispara de novo), cancel cancela pela máquina de estados. Vive em src/clicksign.ts.
DocuSign está preparado, não operando: com esse modo, o envio devolve aviso. Vive em src/docusign.ts.
Envio só conta quando o provedor confirma. Sem confirmação (Clicksign sem token ou recusando, DocuSign, ou nenhum e-mail da Radhr AI saiu, inclusive num ambiente sem RESEND_API_KEY), o contrato fica em rascunho, as assinaturas criadas na hora são canceladas e o evento contrato_envio_falhou registra o motivo. As assinaturas da versão anterior só caem depois de um envio confirmado. Vive em src/assinatura.ts.
White label nas páginas e e-mails ao cliente. A página /c/<token>, o certificado e os e-mails de assinatura usam a identidade da organização (nome, rodapé, tema) e saem pelo remetente dela quando o domínio próprio está verificado no Resend; a Witbiz segue com a marca Witbiz. Vive em src/identidade.ts, src/remetente.ts e src/assinatura.ts.
Cancelamento registra o motivo e cancela as assinaturas pendentes. Vive em src/contratos.ts (cancelarContrato).
Cobrança na Home: rascunho parado há 24 h vira "Revisar e enviar o contrato"; enviado ou visualizado há 72 h sem assinatura vira "Cobrar a assinatura do contrato". Vive em src/hoje.ts.

Casos de uso

Proposta aceita, cliente novo. Converta o lead; o contrato já está em rascunho. Abra, complete CNPJ e endereço da contratante, defina início e fim, envie.
Cliente pediu uma cláusula específica. Edite o texto e salve como nova versão. Se o contrato já foi enviado, reenvie: os links antigos deixam de valer.
O cliente não recebeu o e-mail. Use "Reenviar links"; sem Resend configurado, copie o link exibido na trilha de assinaturas e mande por outro canal.
Mudança de escopo com custo aprovada. O aditivo abre em rascunho na tela de contrato; revise e envie. O Escopo só muda quando ele for assinado.
Proposta errada no contrato. Cancele o contrato com o motivo, corrija a proposta pelo fluxo de propostas e gere outro pelo Cliente 360.
Cliente aceitou a renovação pela página pública. O contrato de renovação já está em rascunho; o e-mail ao Consultor traz "Revisar e enviar para assinatura". Se não nasceu, o e-mail diz o motivo e o botão do 360 gera.
Organização assina pela Clicksign. Em /radar/configuracoes, escolha Clicksign (Profissional ou superior) com o CLICKSIGN_TOKEN configurado; os contratos que nascerem depois disso vão pela Clicksign.
Guardar o contrato assinado em arquivo. Use "Baixar PDF" na leitura do contrato.

Telas

/radar/cliente/:id (aba Contratos e propostas): lista de contratos com status e valor; botão para gerar da proposta aceita (com ou sem IA).
/radar/contrato/:id: cabeçalho com status, versão, provedor, código e valor; avisos de dados faltando; texto com prévia e edição; versões anteriores com hash; cartão Assinaturas (quem, status, quando visualizou e assinou, IP, links e certificado); cartão Escopo e projeto (link ou "Gerar escopo"); datas e renovação; diálogo "Mais…" para mudar status ou cancelar.
/radar/contrato/:id/ver: o texto formatado para imprimir, com "Baixar PDF".
/radar/contrato/:id/pdf: download do PDF da versão atual (<código>-v<n>.pdf).
/radar/configuracoes (admin): modo de assinatura (Radar, Clicksign, DocuSign), dados da CONTRATADA (razão social, CNPJ, e-mail, endereço, representante, cargo, foro) e valor-hora de referência usado nas mudanças de escopo.
/c/<token> (público, com a marca da organização): documento, painel para pedir o código e assinar, lista de signatários.
/c/<token>/certificado (público): hash da versão, trilha de assinaturas e método, com botão de imprimir.
Portal do cliente (/portal/<token>): mostra os contratos não cancelados e o link "Ler e assinar" do próprio cliente (ver funcional/clientes).

Permissões

admin: tudo o que o consultor faz, mais /radar/configuracoes (a única tela deste fluxo restrita a admin).
consultor: gera, edita, regenera, envia, muda status e cancela contratos. As telas de contrato não checam o dono do Cliente: qualquer membro logado da organização age em qualquer contrato dela.
financeiro: gera o contrato pelo 360 e, na página /radar/contrato/:id, edita o texto (salvar), regenera (regerar), ajusta as datas (dados), envia ou reenvia para assinatura (enviar) e cancela (cancelar). Só a troca manual de status fica com consultor e admin. Contrato assinado ou cancelado não muda as datas para ninguém (atualizarDados recusa, como a edição e a regeneração) (src/radar/permissoes.ts).
leitura: só consulta; qualquer ação no contrato é recusada com 403.
cliente (por link): cada signatário acessa só a sua página /c/<token> e o certificado; o token é pessoal e não depende de login.
**Papéis v2 (flag rbac_v2, ligada por organização):** cada escrita passa pelo catálogo de permissões (src/rbac/engine.ts): gerar pelo 360 = contratos.gerar; na página do contrato, enviar = contratos.enviar, cancelar = contratos.cancelar, status = contratos.status, o resto = contratos.editar. Têm todas: owner, admin e master; financial tem todas menos contratos.status; manager, sales, operation e viewer só leem (contratos.ler). Os papéis antigos são traduzidos: admin do vínculo vira owner (master na Witbiz), consultor vira sales — e, portanto, deixa de gerar, editar e enviar contratos —, financeiro vira financial e leitura vira viewer. Salvar /radar/configuracoes exige organizacao.configurar (owner/master). Overrides por usuário somam ou tiram permissões; toda recusa vai para acessos. Com a flag desligada, valem os papéis acima.
Gating de plano: assinatura Radar em todos os planos. Os modos Clicksign e DocuSign exigem o recurso assinatura_externa (Profissional ou superior); sem ele, a configuração volta para Radar com aviso (src/planos.ts, src/radar/contratos.ts).

Perguntas frequentes

Converti o lead e não apareceu contrato. Por quê? O contrato automático só nasce quando a conversão cria um Cliente novo. Se a empresa já era cliente, gere pelo botão na aba Contratos e propostas. Se a geração falhar, o aviso diz o motivo (em geral, proposta não aceita ou sem itens).

Posso mudar um valor direto no texto? Só para um valor que já esteja na proposta aceita ou na versão atual: a edição manual é conferida e recusa R$ novo. Para mudar preço, ajuste a proposta (ou faça um aditivo) e regenere.

A IA pode inventar preço ou prazo no contrato? Não no texto que a Radhr AI grava: o que a IA escreve com R$ fora da proposta ou com percentual é descartado, e a validação final recusa o contrato se sobrar valor estranho.

A assinatura Radar tem validade jurídica? É assinatura eletrônica nos termos da Lei 14.063/2020 e do art. 10, § 2º, da MP 2.200-2/2001, com verificação de posse do e-mail, registro de IP, navegador e instante, hash do documento e certificado. Para casos que exijam certificado ICP-Brasil, trate fora da Radhr AI.

Como uso a Clicksign? Escolha o modo Clicksign em /radar/configuracoes (Profissional ou superior) e configure CLICKSIGN_TOKEN e CLICKSIGN_WEBHOOK_SECRET. "Enviar para assinatura" sobe o PDF e a Clicksign cuida dos e-mails; o webhook conclui o contrato. Sem o token, o envio falha com aviso e o contrato fica em rascunho. Atenção: o contrato guarda o provedor do dia em que nasceu; mudar a configuração depois não troca o de um contrato existente.

Upsell ou renovação geram contrato novo? Sim, quando nascem de uma proposta da oportunidade (/radar/oportunidade/:id/proposta) e ela é aceita. Uma mudança dentro do contrato vigente continua sendo aditivo.

De onde vêm os dias de suporte, o foro e as exclusões do contrato? Do perfil de IA da organização, quando ele define regras contratuais; sem isso, do texto padrão (90 dias de suporte) e do foro cadastrado em /radar/configuracoes.

O que acontece quando todos assinam? O contrato vira assinado, a Oportunidade de origem vai a ganha, todos recebem o certificado e o Scope Builder gera o projeto (ou, no aditivo, a mudança é aplicada ao escopo).

Termos de uso da Radhr AI são contratos daqui? Não. O aceite dos termos de assinatura da Radhr AI pelo admin da organização (planos Essencial e Profissional, em /radar/aceite, src/termos.ts) é outro fluxo: registra versão, quem, quando, IP e navegador na organização e não usa as tabelas de contrato.

Webhooks de saída (ADR-0015)

Quando o Contract Builder gera um contrato, a Radhr AI emite o evento contrato_criado para os webhooks de saída cadastrados pela organização no Developer Hub (/radar/integracoes/desenvolvedor), com id, código, valor, status e tipo do contrato — nunca o texto.