Documentos e assinaturas com Clicksign

O Legame cadastra modelos por nome e pela chave UUID da Clicksign, resolve os campos do CRM, confecciona documentos em um envelope e acompanha as assinaturas por webhook. O texto do Word continua editável: novas variáveis podem ser mapeadas sem alterar o código.

Guia rápido dentro do sistema

O botão Como usar está disponível nas configurações, no editor de modelo e no painel do negócio. Ele explica cadastro de clientes, Word, preenchimento, papéis, revisão, automações e correção de documentos vazios. A tela organiza o trabalho em três passos e apresenta os nomes dos dados do CRM no seletor de origem.

1. Complete os clientes em Contatos → Editar. Os dados pessoais, empresariais e de endereço também estão no cadastro rápido e na visão 360. Os campos são opcionais para salvar um contato, mas a qualificação obrigatória é validada antes da geração.
2. Cadastre as pessoas do escritório em Configurações → Clicksign → Representantes da empresa. Dados obrigatórios: nome completo e e-mail. CPF, telefone e nascimento são opcionais; quando informados, são validados. Inativar impede novos envios, preservando os anteriores.
3. Edite o modelo: leia o DOCX e use a sugestão de procuração ou contrato. Confira se os nomes das variáveis coincidem com o Word. A sugestão ajusta os clientes para Outorgante ou Contratante; adicione a regra da empresa e escolha seu papel. Datas ou nomes escritos literalmente no Word não mudam pelo mapeamento.
4. No negócio, escolha quem assina, revise a prévia e gere um rascunho. Abra o documento antes de ativar os convites.

Modelos sem campos não podem ser salvos ou usados sem confirmação explícita de Texto fixo. Modelos antigos vazios ficam bloqueados até serem corrigidos. Quando a API não listar as variáveis, a leitura local do DOCX continua disponível.

Os 25 novos campos incluem nome social, nascimento, sexo, nacionalidade, naturalidade, estado civil, profissão, identidade, filiação, dados empresariais e endereço. Datas devem usar AAAA-MM-DD; campos ausentes em atualizações de API preservam os valores existentes, e null limpa o campo. A API pública, importação, exportação e mesclagem de clientes preservam os dados nativos. A migração aproveita campos personalizados compatíveis já existentes; os caminhos antigos continuam disponíveis, com preferência pelos dados nativos preenchidos.

Representantes da empresa definidos no modelo são usados também pelas automações. No envio manual, os participantes do modelo são selecionados inicialmente e podem ser desmarcados. O papel, canal, autenticação e ordem vêm da regra do modelo; uma pessoa adicionada apenas no envio usa Outorgado em procuração ou Contratada nos demais documentos. Para escolher outro papel, configure a regra antes de enviar.

Alterações no modelo, no cliente ou no representante não mudam o documento já gerado: o envio mantém os dados revisados. Para corrigir um documento anterior, cancele-o quando necessário e gere um novo rascunho. Não use Tentar novamente esperando que isso refaça a qualificação: a tentativa retoma o envio original.

Instalação e conexão

1. Atualize o CRM e o serviço legame-scheduler, seguindo o procedimento do ambiente em DOCKER-AMBIENTES.md. As migrações PostgreSQL 0017_clicksign.sql e 0018_clientes_assinaturas.sql são aplicadas pelo provisionamento existente. A segunda amplia os clientes e cria representantes da empresa, preservando dados existentes. Ela cria configuração, modelos, envios, documentos e eventos; não importa documentos da conta Clicksign automaticamente.
2. Mantenha LEGAME_SECRET_KEY, LEGAME_CRON_SECRET, LEGAME_COMPANY_ID, armazenamento persistente e LEGAME_PUBLIC_ORIGIN configurados. A origem pública deve ser a URL HTTPS do Legame acessível pela Clicksign. Preserve a chave de criptografia ao restaurar backups.
3. Em Configurações → Clicksign, escolha sandbox ou produção, informe o access token da conta e salve. Os ambientes têm tokens, modelos e webhooks próprios.
4. Na conta Clicksign, cadastre um webhook para a URL exibida pelo Legame: https://seu-legame/api/integrations/clicksign/webhook. Habilite sign, auto_close, close, document_closed, cancel, deadline e refusal. Copie o segredo HMAC desse webhook para a configuração do Legame.
5. Ative a integração, salve e use Testar conexão salva. O teste valida acesso à API; a entrega do webhook deve ser conferida com um envio no sandbox e com o indicador de último evento recebido.
6. Confira que o serviço legame-scheduler está executando a versão atual. Ele processa a fila Clicksign a cada 30 segundos, independentemente das rotinas financeiras. Sem ele, os envios e downloads permanecem na fila.

Os tokens e o segredo HMAC ficam criptografados no banco; a API e a interface retornam apenas indicadores de configuração. Os perfis precisam de integracoes:administrar para cadastrar conexão e modelos. A produção utiliza app.clicksign.com/api/v3; o sandbox utiliza sandbox.clicksign.com/api/v3.

Para testar o agendador uma única vez no ambiente configurado:

node scripts/scheduler.mjs --once

Esse comando também executa as rotinas existentes de financeiro, chamados e campanhas. O endpoint interno POST /api/cron/clicksign exige Authorization: Bearer <LEGAME_CRON_SECRET>. O intervalo opcional LEGAME_CLICKSIGN_INTERVAL_MS tem padrão de 30000 ms e mínimo de 15000 ms; precisa estar disponível no processo do agendador caso seja alterado.

Modelos e variáveis

Em Adicionar modelo, informe nome, tipo de documento do Legame e chave do modelo na Clicksign. Use Validar chave e importar campos. Se a API não apresentar as variáveis, use Ler variáveis do DOCX: a leitura identifica campos mesmo quando o Word divide a variável entre trechos de formatação, inclusive cabeçalhos e rodapés.

Também é possível Cadastrar este DOCX na Clicksign diretamente pela tela. Depois do upload, salve o mapeamento no Legame. Alterar o conteúdo de um modelo Word exige criar um novo modelo na Clicksign e atualizar sua chave; a edição do mapeamento, das regras de assinatura e do nome pode ser feita no Legame. Arquivar desativa o uso em novos envios e preserva o histórico.

Cada variável tem nome, rótulo, modo de preenchimento, formato, obrigatoriedade e valor alternativo. Os modos são:

O catálogo inclui os campos personalizados ativos de cliente, negócio e orçamento. Use a chave do campo personalizado, e não seu nome exibido: cliente.campo.profissao, negocio.campo.descricao_servico, orcamento.campo.observacao. Campos opcionais podem ter um valor alternativo. Campos obrigatórios vazios impedem a criação remota e aparecem na revisão.

Os formatos disponíveis são texto, moeda sem símbolo (1.234,56), moeda com símbolo (R$ 1.234,56), data, data por extenso, número e JSON. Também funcionam dentro do texto: {{cliente.data_nascimento|data}}. Para tabelas dinâmicas de um modelo Clicksign, mapeie uma variável para produtos.lista e use JSON; a estrutura da tabela deve estar definida no DOCX. As tags de controle de tabela e posicionamento não são tratadas como campos de texto comuns.

Campos dos DOCX de contrato e procuração

As sugestões abaixo são editáveis. Cadastre os campos personalizados que ainda não existirem ou escolha outro modo, como preenchimento manual.

Exemplo editável de qualificação, repetido para cada cliente:

{{cliente.nome}}, {{cliente.nacionalidade}}, {{cliente.estado_civil}}, {{cliente.profissao}}, CPF {{cliente.documento}}, RG {{cliente.rg}}, residente em {{cliente.endereco}}

A sugestão padrão é {{cliente.qualificacao}}, calculada com os campos nativos do cadastro. Para PF, exige nome, CPF, nacionalidade, estado civil, profissão e endereço (logradouro, número, cidade e estado). Para PJ, exige nome, CNPJ e endereço. RG e órgão emissor são incluídos quando informados. A prévia lista os dados faltantes por cliente. O texto acima é uma alternativa personalizada. Acrescente naturalidade, nascimento, filiação, representação ou outros dados que seu documento exigir. A obrigatoriedade valida cada cliente incluído no texto.

O total financeiro vem do plano financeiro, do orçamento selecionado ou do valor definido do negócio, nessa ordem. O valor da parcela é sugerido apenas quando as parcelas existentes têm valor uniforme; caso contrário, preencha manualmente ou use outro texto. O orçamento padrão é o aprovado mais recente, ou o último disponível. Dados financeiros e de orçamento respeitam as permissões do operador. As datas e os valores ficam congelados no envio: um rascunho ativado dias depois preserva a data de confecção até que seja cancelado e confeccionado novamente.

Signatários e representados

As regras de assinatura são independentes da qualificação do documento. Uma regra pode incluir todos os clientes, apenas o principal, contatos, parceiros, um representante cadastrado da empresa ou uma pessoa definida na própria regra. Essa pessoa também pode receber dados de campos do CRM, como {{negocio.campo.representante_nome}}.

Configure nome, e-mail, telefone, CPF e nascimento opcionais, papel, grupo de assinatura, canal do convite e autenticação. Nome e sobrenome, contato exigido pelo canal, CPF informado e nascimento são validados antes do envio. Telefones são enviados com DDD e sem DDI. A Clicksign solicita CPF/nascimento no fluxo de assinatura quando esses dados não foram preenchidos. Para pessoa jurídica, configure a pessoa física representante como signatário; o CNPJ pode continuar na qualificação da empresa.

Na lista de clientes do negócio, os contatos adicionais podem ter o papel Representante legal do cliente, Parceiro ou Contato financeiro. Salve os vínculos antes de gerar. As sugestões de qualificação usam Clientes (principal e contatos); representantes podem ter uma regra de assinatura separada com a seleção Representantes legais dos clientes.

Para um cliente representado, mantenha sua qualificação no documento e escolha o representante entre os clientes vinculados ou em uma regra própria. No envio manual é possível desmarcar clientes que não assinam e escolher os representantes da empresa para cada documento. Nas automações, configure as regras do modelo para incluir os signatários corretos, pois não existe seleção humana durante a execução.

Os papéis incluem contratante, contratada, outorgante, outorgado, testemunha, responsável legal e advogado. Grupos permitem assinatura em ordem. A interface oferece token por e-mail, SMS ou WhatsApp, assinatura manuscrita, selfie, documento oficial, comprovante de endereço, selfie dinâmica e certificado ICP Brasil; a disponibilidade depende da conta Clicksign. Use no máximo um tipo de token por regra.

Confecção no negócio e automações

No negócio, abra a aba Documentos → Assinaturas Clicksign → Confeccionar documentos. Selecione um ou mais modelos, o orçamento, os clientes signatários, os representantes da empresa e o objetivo. Revise os campos e signatários; os valores podem ser corrigidos na revisão para esse envio. Uma alteração exige revisar novamente. Se os dados do CRM mudarem depois da prévia, o Legame exige uma nova revisão.

Confeccionar para revisão cria o envelope, documentos e requisitos como rascunho. O botão Ver documento permite conferir o PDF original gerado pela Clicksign. Depois, Enviar para assinatura ativa o mesmo envelope e solicita os convites, sem recriar seus documentos. Confeccionar e enviar para assinatura executa as duas fases na fila.

Em Automações, a ação Confeccionar documentos Clicksign permite selecionar modelos e escolher rascunho ou assinatura. Funciona nos gatilhos existentes por etapa e status do negócio e mudança de status de orçamento/tarefa vinculados ao negócio. Campos manuais obrigatórios precisam de valor inicial ou devem ser mapeados para dados já preenchidos. Se faltarem dados, a execução registra a falha antes de criar documentos. O sucesso da ação significa enfileirado; o resultado da confecção e das assinaturas é acompanhado no negócio.

O operador precisa de acesso ao negócio e de permissão para criar documentos e editar negócios; alterações de um envio exigem editar documentos e negócios. O worker verifica novamente usuário ativo, permissões e acesso à etapa antes de executar a operação externa. Os registros de envio, documento e evento também têm políticas PostgreSQL de acesso por negócio.

Acompanhamento e arquivos

O webhook verifica Content-Hmac sobre o corpo original, descarta eventos de documentos não associados ao Legame e grava eventos deduplicados antes de responder. O processamento ocorre na fila. A assinatura de cada pessoa, os estados do documento e os principais eventos aparecem no painel e na linha do tempo.

auto_close indica conclusão das assinaturas. close manual não equivale a todas as assinaturas concluídas: o painel distingue Finalizado · confira assinaturas de Todas as assinaturas concluídas. Eventos antigos de assinatura não reabrem um documento finalizado. Quando os tipos do Legame possuem status de andamento correspondentes, o documento local acompanha confecção, assinatura em andamento e conclusão.

O PDF final é baixado após document_closed, quando a Clicksign confirma que o arquivo está pronto. Ele é armazenado privadamente no Legame e passa a usar os fluxos existentes de documentos e portal. Cada tentativa obtém uma URL atual; URLs temporárias não ficam salvas como arquivo final. A tela consulta o banco local a cada 15 segundos enquanto estiver visível. Não existe consulta periódica de status na API Clicksign.

São mantidos os limites atuais do Legame: DOCX e PDF de até 2 MB e quota de 1 GB por workspace. Falta de espaço, PDF maior que o limite ou indisponibilidade temporária aparecem no documento. Depois de resolver, use Tentar baixar PDF final. O envio pode ter todas as assinaturas concluídas e ainda aguardar o armazenamento do PDF.

Recuperação de falhas

Cada envio tem uma chave de idempotência, uma cópia dos dados resolvidos e um registro das etapas remotas. A mesma solicitação não cria outro envelope; a mesma chave com conteúdo diferente é rejeitada. Pessoas compartilhadas pelos documentos usam um signatário no envelope, com requisitos associados a cada documento correto.

Limites de API e trabalhos interrompidos podem continuar na fila. Uma criação cuja resposta se perdeu entra em Operação sem confirmação, sem repetição automática. Use Reconferir envelope: informe a chave ou deixe vazio para pesquisar o nome exclusivo do envio. O Legame consulta documentos, signatários e requisitos antes de continuar. Uma etapa ausente só pode ser repetida após nova conferência e confirmação explícita na tela, com espera mínima de 10 minutos. Se houver operações remotas sem confirmação, reconcilie antes de cancelar.

Quando o convite pode ter sido enviado mas sua resposta se perdeu, o envelope permanece ativo e exibe aviso. Um novo lembrete exige ação do operador. Tentar novamente aplica-se às falhas sem operações pendentes de confirmação. O cancelamento preserva documentos já finalizados. Modelos e histórico são preservados; negócios/documentos com vínculos de assinatura não são eliminados fisicamente pelo descarte automático.

O upload de um novo modelo DOCX é uma operação direta: se sua resposta se perder, confira os modelos na Clicksign e utilize a chave criada antes de repetir o upload.

Verificação

Os testes em tests/clicksign-integration.test.mjs utilizam PostgreSQL emulado com políticas de acesso e transporte Clicksign simulado. Cobrem DOCX fragmentado, campos personalizados, múltiplos clientes/documentos, configuração e segredos, idempotência, prévia, automações, assinaturas, HMAC, PDF privado, perda de resposta, reconciliação, limites de API e revogação de acesso. O teste do agendador inclui /api/cron/clicksign.

Não há validação com token real neste conjunto de testes. Antes do uso em produção, faça um fluxo completo no sandbox com a própria conta: confeccionar os dois modelos, revisar, assinar, receber os webhooks e abrir o PDF final no Legame.

Documentação oficial consultada: fluxo da API, modelos, signatários, HMAC e evento do PDF final.