6.4. Módulos

📍 Onde ler no portal

Esta página descreve o papel de cada módulo na esteira e as regras que o contrato da API não conta.

Schema de steps, endpoints, canais, tipos de campo e o ciclo criar → publicar → executar estão descritos em outras páginas — não são repetidos aqui.

Exemplos completos de cada combinação de step estão no Try It de Criar Flow.

🧭 Como a esteira encaixa os módulos

O ClickFlow não executa coleta, biometria, KYC, aceite ou assinatura por conta própria. Ele orquestra módulos desacoplados: cada um tem input, lógica interna e output próprios, e pode ser usado sozinho ou como etapa de uma jornada.

🧩 1. Módulo de Coleta de Dados (form)

O que é. Motor de coleta, validação e estruturação de informações. Opera via API, devolve JSON e despacha por webhook. Não gera documento. Pode ser contratado sozinho ou entrar como porta de entrada da esteira.

O que faz. Mostra um formulário em webview (WhatsApp ou o canal do integrador), valida o que a pessoa preenche e devolve um payload estruturado. O cliente injeta o que já sabe (ERP/CRM) e a pessoa só confirma ou completa o que falta — o Smart Fill.

Como funciona na esteira. O step form aponta para uma Version já criada no ClickForm (context.version_key). O Executor abre a webview. Quando o preenchimento termina, o Form avisa o Executor e a jornada avança. Respostas de um form podem pré-preencher o próximo (context_map_keys) e alimentar Assinatura ou Aceite via {{chave-do-campo}}. Schema do step: Orquestrador. Como criar Form, Version e Run: Primeiros passos do Form.

O que a esteira muda no uso do Form

• Três modelos de uso. Só ClickForm (coleta para o ERP, sem assinatura); ClickForm como step do Flow; Form coletando e o cliente chamando a API de Modelos por conta própria.
• Anexo não entra no contrato. Upload (file / image) fica disponível para download na execução ou no webhook do Form. Não vai sozinho para o envelope de Assinatura.
• CEP inteligente. O tipo cep autopreenche logradouro, cidade, UF, bairro, número e complemento — o catálogo de attribute_type está em Criar e utilizar formulários.
• Repeater. Clona um bloco (ex.: vários dependentes) e devolve array de objetos.

Tipos de campo, Skip Logic (conditions), pré-preenchimento (context no Run) e Access Verification: Criar e utilizar formulários. Referência: Forms, Versions, Runs.

🧩 2. Módulo de Identidade (verify)

O que é. Módulo de verificação de identidade (prova de vida e biometrias). Roda como etapa própria da jornada, independente do requisito de autenticação do envelope de Assinatura. O que foi aprovado aqui não libera automaticamente a assinatura na API da Clicksign, e vice-versa.

O que faz. Confirma que a pessoa é quem diz ser, com captura em webview. O Flow declara o tipo de autenticação e, se quiser, a ordem de tentativa dos provedores; o Verify executa e devolve o resultado.

Matriz autenticação × provedor

* o type caf corresponde ao fornecedor "Certta".

Como funciona na esteira. O step verify leva authentication e, se houver um form antes, pode casar campos coletados com a identidade via contact_fields_map. Schema do context: Orquestrador.

Observações sobre o comportamento do módulo:

• Prova de vida (liveness) não possui o retorno inconclusivo — o desfecho é aprovado ou reprovado. Demais tipos de verificação, quando devolvem "inconclusivo", não implicam necessariamente em uma interrupção da jornada do cliente.
• Reprovação da verificação, no padrão, encerra a jornada sem nova tentativa (retentativa automática seria vetor de fraude).
• Com result_policy: "passthrough", o step é marcado como falho, a execução segue e o template de rejeição do WhatsApp não é enviado — caminho necessário quando o KYC é quem arbitra o desfecho. passthrough cobre reprovação (resultado negativo válido); não cobre falha operacional do provedor (sem resultado, ou resultado incompleto), que sempre falha o step e a execução.

Subopções — o que cada tipo implica na esteira

• liveness. Prova de vida. Sem resultado inconclusivo. Admite caf e clearsale — provider_priority tem efeito prático.
• biometric_behavior. Biometria 1:N. Produz o sinal de alerta de fraude (identity_fraudsters_result) que o KYC consome. Sem este tipo antes, um step kyc falha na execução — a publicação do Flow não valida a sequência.
• identity_biometrics. Mesma família de captura da biometria 1:N, sem o sinal de fraude; quando o resultado é inconclusivo, devolve risk_score (0–100). Não habilita KYC depois.
• provider_priority. Array opcional com a ordem de tentativa (mais prioritário primeiro).
• instructions. Flag opcional. Quando true, o Verify exibe a tela de instruções antes da captura. O Flow não desenha nem customiza essa tela — conteúdo e layout são do módulo.

🧩 3. Módulo de KYC (kyc)

O que é. Módulo de avaliação cadastral e de risco (pessoa). Não é autenticação facial: o Verify confirma a face; o KYC consulta bases e devolve uma decisão de risco.

O que faz. Recebe o contexto da jornada (e o sinal de fraude vindo do Verify), avalia CPF e responde de forma binária: APPROVED ou REJECTED, com evaluationId para auditoria. Não tem webview — o contato não "vê" o KYC; a esteira espera o webhook e aplica o desfecho.

Como funciona na esteira. O step kyc declara context.type (customer = CPF). Schema: Orquestrador.

Na prática vem depois de um verify com authentication: "biometric_behavior" e result_policy: "passthrough". Sem o passthrough, a reprovação da biometria encerra a execução antes de o KYC avaliar. Só biometric_behavior alimenta o KYC — liveness e identity_biometrics não servem de precedência.

O Flow é linear: não há if/else para outro caminho. O KYC é o árbitro — APPROVED segue a jornada; REJECTED falha a execução para o contato. A régua de risco e de negócio é configurada e avaliada dentro do módulo de KYC, não no Flow e não pelo integrador depois do fato.

🧩 4. Módulo de Assinatura (signature)

O que é. Etapa de formalização eletrônica. O motor é o da API da Clicksign. A esteira é pass-through: aceita o que a API de Assinatura define e repassa íntegro. Comportamento de campo de envelope ou de signatário não é decisão de produto do Flow — a fonte é a documentação de Envelope.

O que faz. Cria o envelope, convoca os signatários e aguarda a conclusão. O contato assina na webview da jornada (WhatsApp ou o canal api). Quando a API da Clicksign confirma a assinatura, o Executor avança o step.

Como funciona na esteira. O step signature declara documentos, signatários extras (se houver) e configurações do envelope. O contato dinâmico da execução entra como signatário; outros (testemunha, fiador, segundo titular) vão em signers[]. Identidade de qualquer item da lista pode vir de um form anterior, via {{chave-do-campo}}.

Documento. O Flow aceita template, arquivo no S3 (file) e arquivo no disparo (runner_files). Schema no Orquestrador e no Criar Flow; upload no disparo no Executor e em Iniciar execução; comportamento de modelo, documento e envelope em Automação com Modelos, Documentos e Envelope.

Configuração. Envelope (settings) e signatários extras (signers[]): schema no Orquestrador; comportamento em Envelope, Campos e regras do envelope e Signatários.

O que a esteira faz diferente da API da Clicksign sozinha

• Só o evento sign avança a jornada. Recusa, vencimento ou cancelamento do envelope ainda não encerram a execução.
• Assinatura presencial (presential) não é suportada — a API da Clicksign devolve erro.
• Cancelar a execução não cancela o envelope na API da Clicksign.
• Observadores do envelope e rúbrica posicionada não estão disponíveis no Flow.
• Omitir settings.name usa o padrão {nome da esteira} - {contato} - {data/hora}.

🧩 5. Módulos de Aceite e Notificação (consent)

O que é. Módulo de aceite formal de um termo (novas condições, políticas, ciência). Não gera PDF: a evidência legal e o artefato principal são o recibo estruturado de auditoria (trail de status) devolvido via webhook. Não confundir com o step acceptance, que só pede para a pessoa tocar em continuar.

O que faz. Envia o conteúdo do termo pelo canal configurado, rastreia a evolução do status (do envio à leitura), registra a decisão e devolve o recibo com o desfecho para a esteira. Desfechos de recusa ou expiração encerram a jornada.

Como funciona na esteira. O step consent aponta para um template_id já cadastrado no módulo de Aceite e declara o canal. O Executor cria o aceite via API, injetando o execution_id e a URL de webhook (isso não vai exposto no JSON do Flow), e aguarda o recibo final assíncrono. A esteira não reenvia por conta própria — o gerenciamento de reentrega, retry de webhook e idempotência é feito internamente pelo módulo. Schema do context: Orquestrador.

Atenção: falhas síncronas na criação (400/401/403/422) encerram a execução na hora, pois nenhum aceite foi gerado.

Subopções — o que o schema não conta

• Canal. channel_type é obrigatório. Único valor válido hoje: whatsapp.
• Template. template_id é ponteiro para o cadastro interno do Aceite. O desenho dos passos (textos, botões, transições) vive na configuração do template, não no Flow. Três padrões usam o mesmo contrato:
  1. Passo único com botões diretos de decisão.
  2. Passo informativo (auto-enviado) + passo de decisão.
  3. Passo com botão de navegação (ex.: "Continuar") + passo de aceite.
• Variáveis (channel_params). Preenche os marcadores do template WhatsApp (header / body), mapeados por step_id. Cada posição aceita placeholder de contato ({{person_name}}), texto literal ou chave de um form anterior.
• Metadados. metadata (chave-valor) entra no relatório e é devolvido no recibo final — útil para correlacionar com PNR, número de proposta, CPF, etc.
• Desfechos. Ciclo PENDING → SENT → DELIVERED → READ. Finais irreversíveis: ACCEPTED, DECLINED e EXPIRED. Não existe status FAILED.

Observações

• O Flow lista steps e serviços que não são módulos. Quem decide o próximo passo e quem aciona o módulo está em Primeiros passos do Flow.
• Orquestrador e Executor. São os dois serviços da esteira (cérebro e músculo), não unidades de negócio plugáveis. Orquestrador · Executor.
• acceptance. Confirmação de leitura. Mensagem no WhatsApp com botão de continuar — serve para a pessoa seguir a jornada, não para registrar aceite de termo. Não é módulo. Aceite formal é o módulo de Aceite (consent). Os dois convivem; nenhum substitui o outro. Se o passo precisa de evidência de consentimento, use consent. context de acceptance (template_key, accept_replies) está no Orquestrador.