Orquestrador

O ClickFlow Orchestrator é o serviço central de governança da esteira: guarda a definição estrutural do flow e o estado de cada execução, e decide qual é o próximo passo — sem executar nada e sem conhecer o canal de comunicação com o usuário final.

💾 Modelo de dados

A API é stateless e possui duas entidades:

• Flow — a definição: nome + lista ordenada de steps.
• Execution — uma instância de um flow publicado, em execução: passo atual, histórico de passos, status.

Status do Flow

Status da Execution

running · waiting · completed · failed · canceled — este último é definitivo (POST .../cancel é irreversível; /next passa a responder 409).

🧩 Tipos de step

Cada step do flow tem um type e um context cujo formato depende do tipo. O funcionamento de cada módulo está em Módulos.

result_policy: "passthrough" cobre reprovação (resultado negativo válido): a etapa conclui, a execução segue e o veredito fica em verify_result_unjudged, no contexto da etapa, sem ser aplicado. Não cobre falha operacional do provedor do Módulo de Autenticação (sem resultado, ou resultado incompleto), que sempre falha o step e a execução, mesmo com passthrough declarado.

signature e embedded_signature definem a experiência do Módulo de Assinatura. O canal da execução continua sendo definido no disparo pelo Executor (whatsapp, api ou web). signers[] vale para signature. No embedded_signature, o único signatário é o contato da execução. embedded_signature ainda não está disponível no canal web; em breve, passa a funcionar nesse canal.

template, file e runner_files são o documento do envelope. runner_files é esse documento enviado a cada disparo, no lugar do modelo ou do arquivo no S3. form_attachment cria outro documento no mesmo envelope, a partir de um anexo de Form, para o arquivo ter validade jurídica. Não substitui o documento principal.

signature_watchers[] declara observadores do envelope e vale para signature. Em embedded_signature, ainda não está disponível. Um observador acompanha a formalização e pode receber avisos, mas não assina, não autentica e não entra na conclusão da etapa. email é obrigatório. kind vale all_steps (todo o processo) ou on_finished (só a conclusão). communicate_events escolhe os avisos, e attach_documents_enabled define se os documentos finalizados vão anexados. O significado de cada campo é o da criação de observador na API de Assinatura.

deadline_at, em settings, aceita um inteiro de 1 a 90 ou uma data em ISO 8601. Acima de 90, zero, negativo ou número quebrado, a publicação recusa. O inteiro vira a data de hoje em UTC mais esses dias, calculada na criação do envelope. Sem o campo, a Assinatura aplica o prazo padrão de 90 dias.

Exemplos completos de cada combinação estão nos exemplos do endpoint POST /flows na referência (aba Try It!).

Injetar dados no flow

Dá para declarar {{chave}} no flow e preencher o valor na execução. Na mesma chave, o contact vence o context, e o context vence a resposta do formulário. Chave sem valor vira string vazia.

O sistema já tem o dado. A identidade do cliente da esteira vai no contact do disparo: person_name, person_documentation, phone_number, person_birthday e person_email. Pedido, cônjuge e o restante vão no context. O body do disparo está em Contexto no disparo.

O dado é coletado ou confirmado num Form. A resposta segue para os passos seguintes pela key do campo, como {{nome-fiador}}. Um step form com contact faz outra coisa: a field key atualiza a identidade do cliente da esteira, e os passos seguintes passam a ler esse contact. O exemplo é Form — atualização de contato, na aba Try It! de Criar flow. Se um Form posterior deixa o campo editável, o passo que consome o valor aponta para a key desse Form de confirmação.

Onde o valor aparece. No Form, no envelope e no arquivo, na mensagem de consentimento e nos signatários. O detalhe de cada destino está em Onde funciona.

Signatário extra. É o caso que melhor mostra a injeção de ponta a ponta. A pessoa muda a cada execução e não é o cliente da jornada: cônjuge, fiador, avalista. A chave fica no item de signers[]. O valor vem do context do disparo, como {{spouse_name}}, ou da key de um campo de Form, como {{nome-fiador}}. Com signers[] preenchido, o Executor cria só quem está na lista, e o cliente da esteira entra nela com os placeholders do contact. Sem a lista, o único signatário é o contact.

{
  "name": "Proposta Crédito — signatário extra com variável do disparo",
  "steps": [
    {
      "type": "signature",
      "context": {
        "documents": [
          {
            "kind": "file",
            "s3_bucket": "bucket",
            "s3_key": "contrato.pdf",
            "filename": "Contrato_{{order_id}}_{{person_name}}.pdf"
          }
        ],
        "settings": {
          "name": "Envelope {{order_id}} — {{person_name}}",
          "default_subject": "Assine, {{person_name}}",
          "default_message": "Pedido {{order_id}}.",
          "deadline_at": 7
        },
        "signers": [
          {
            "name": "{{person_name}}",
            "documentation": "{{person_documentation}}",
            "phone_number": "{{phone_number}}",
            "birthday": "{{person_birthday}}"
          },
          {
            "name": "{{spouse_name}}",
            "documentation": "{{spouse_cpf}}",
            "phone_number": "{{spouse_phone}}",
            "email": "{{spouse_email}}"
          }
        ]
      }
    }
  ]
}

O disparo que preenche o cliente, order_id e spouse_* está em Contexto no disparo, no Executor. O mesmo flow é o exemplo Signature — signatário extra com variável do disparo, na aba Try It! de Criar flow. Se o signatário extra for coletado num Form, o exemplo é Signature — identidade do signatário vinda de form anterior.

Onde funciona

• Form. context_map_keys pré-preenche um campo deste Form. Com {{chave}}, o valor vem do contact ou do context do disparo, e o value precisa ser só o placeholder: "Pedido {{order_id}}" não interpola. Com a field key nua, sem {{ }}, o valor vem de um Form anterior. Exemplos Form — Injeção de dado do disparo no formulário, Form — Injeção do contato no formulário e Form — Injeção de respostas de formulários anteriores.
• Envelope e arquivo. settings.name, default_subject, default_message e documents[].filename aceitam {{chave}} no meio do texto. Exemplo Signature — template + configurações do envelope.
• Conteúdo do documento de modelo. Em documents[] com kind: "template", template_mappings declara qual dado preenche cada variável do modelo. A chave do mapa é a variável. O valor é uma chave nua, sem {{ }}: resposta de um Form anterior, chave do context do disparo ou campo do contato. A busca segue essa ordem. Com o mapa presente, inclusive {}, o preenchimento usa só esse lookup. Campo omitido ou null mantém o preenchimento por IA. Chave ausente ou valor vazio vira string vazia. A resposta do Form que entra nesse lookup é a chave enviada no webhook de conclusão, em responses. Se o campo tem external_key, declare essa chave já em snake_case, como customer_full_name. Se não tem, declare a key interna, como nome-completo-821962496a9d. O GET do Run continua na key interna e não serve de referência para o mapa. O filename, quando informado, continua aceitando {{chave}}.
• Anexo do Form como documento a mais. Em signature, kind: "form_attachment" pega o arquivo de um campo file ou image de Form anterior e cria outro documento no mesmo envelope, para esse arquivo ter validade jurídica. Não é o documento principal e não substitui template, file nem runner_files. A field_key é a chave desse anexo no webhook de conclusão: a external_key já em snake_case, quando o campo tem esse atributo; a key interna, quando não tem. Campo opcional vazio é ignorado; se nenhum documento restar, o step falha sem criar envelope. Não funciona em repetidor/lista nem em embedded_signature, e não aceita filename.
• Mensagem de consentimento. channel_params.steps[].variables, no header e no body, aceita texto fixo e {{chave}}. Exemplo Consent — variáveis por step (channel_params).
• Signatários. Em signers[], aceitam {{chave}} os campos name, email, phone_number, documentation e birthday. O e-mail de signature_watchers[] também aceita. Exemplos Signature — signatário extra com variável do disparo e Signature — identidade do signatário vinda de form anterior.
• Fora dessa injeção. O verify não lê o context do disparo: nome e documento vêm do contact e, se faltarem, de um Form via contact_fields_map, com chave nua. signature_host.name e signature_host.email usam só o contact. deadline_at não aceita {{chave}}: é um inteiro de 1 a 90 dias ou uma data fixa em ISO 8601.

Cada nome abre Criar flow. Na aba Try It!, escolha o exemplo por esse nome.

📍 Endpoints

Referência completa, com Try It!: Orquestrador.

🔒 Autenticação

Header Authorization com o UUID do access_token (sem Bearer), validado por introspecção. Para obter o token, veja Access token.

Próximo passo ➡️

• Executor — inicie a jornada e entregue cada etapa ao canal escolhido.
• Módulos — entenda as capacidades que podem compor os steps do flow.
• Collections — teste os endpoints do Orquestrador em Postman, Insomnia ou Bruno.
• FAQ: dúvidas em ClickFlow — respostas curtas para as dúvidas mais comuns.