Executor (Runner)

O Executor — chamado de Runner no contrato técnico (ClickFlow Runner API) — é a ponte entre o Orquestrador e o mundo externo. A cada passo, ele consulta o Orquestrador ("o que eu faço agora?"), aciona o módulo indicado e entrega a experiência ao canal do contato. O Executor não decide a ordem do flow — só executa.

🚀 Iniciar e acompanhar uma execução

Iniciar

POST /api/v1/flows/{flow_id}/execute

{
  "channel": "whatsapp",
  "contact": {
    "person_name": "Maria da Silva",
    "person_email": "[email protected]",
    "phone_number": "5511999999999",
    "person_documentation": "52998224725",
    "person_birthday": "1990-05-06"
  }
}

person_email é opcional. Quando preenchido, o Executor repassa esse e-mail à etapa de Assinatura. Ele não substitui o email de um signatário extra em signers[] e não escolhe o canal do disparo.

callback_url também é opcional. Com ele, o Executor avisa o andamento da execução. O formato dos eventos está em Webhooks.

O parâmetro channel

api e web não são o mesmo canal. Em api, sua empresa entrega os links de current_step. Em web, a Clicksign devolve web_url para conduzir a jornada no navegador. embedded_signature ainda não está disponível no canal web; em breve, passa a funcionar nesse canal.

Exceção: steps acceptance sempre disparam WhatsApp (é uma interação funcional) e falham sem phone_number, mesmo em channel: api ou channel: web. Resposta que não está em accept_replies é ignorada e a etapa continua em andamento. Não há recusa que falhe a execução. O step consent também entrega a mensagem inicial no WhatsApp em api e web, e exige telefone. Sem expiration_time, o aceite expira em 2 horas. A mensagem de conclusão do Aceite só sai no canal whatsapp.

No WhatsApp, envie phone_number com DDI. O Executor grava só dígitos, com 55 na frente e sem +. 11999999999 e +5511999999999 viram 5511999999999. O 55 de um DDD não é lido como DDI quando o número já tem o tamanho de um celular com DDD.

Contexto no disparo (context)

Dá para injetar dados no flow. O {{chave}} é declarado no flow. Este objeto é o caminho de quando o sistema já tem o dado. O outro caminho é um Form, que reutiliza a resposta nos passos seguintes ou atualiza o cliente da esteira. Form, envelope, conteúdo de documento criado a partir de modelo, mensagem e signatário estão em Injetar dados no flow.

Objeto opcional, chave-valor livre, para dados que o seu sistema já tem. Resolve placeholders em nome de documento, dados do envelope, signatários, pré-preenchimento de formulário (context_map_keys) e variáveis de consent. Também alimenta o conteúdo de documents[] com kind: "template": nesse caso, o mapeador do modelo usa os dados do contact, do context e de Forms anteriores, sem exigir {{chave}} no documento. Na mesma chave, o contact vence o context, e o context vence a resposta de um formulário anterior. Chave sem valor vira string vazia. É objeto, não array. Teto de 150 KiB depois do JSON; acima disso o POST /execute responde 400 e não cria a execução. O body inteiro do disparo, incluindo files[], tem teto de 16 MiB. Acima disso a execução também não é criada. Omitir o campo mantém o comportamento anterior.

Exemplo: signatário extra

O payload do flow e os outros destinos estão em Injetar dados no flow, no Orquestrador. No disparo, o cliente vai em contact e o signatário extra vai em context. Com signers[] preenchido, o Executor cria só quem está na lista, então o cliente entra nela com {{person_name}}, {{person_documentation}}, {{phone_number}} e {{person_birthday}}. Sem a lista, o único signatário é o contact. O body abaixo é o exemplo de Iniciar execução. O flow correspondente é Signature — signatário extra com variável do disparo, na aba Try It! de Criar flow.

No flow, dentro do step signature:

"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}}"
  }
]

No disparo:

{
  "channel": "whatsapp",
  "contact": {
    "person_name": "Maria Silva",
    "person_documentation": "12345678909",
    "person_birthday": "1990-01-01",
    "phone_number": "+5511999999999"
  },
  "context": {
    "order_id": "PED-1001",
    "spouse_name": "João Silva",
    "spouse_cpf": "529.982.247-25",
    "spouse_phone": "+5511988887777",
    "spouse_email": "[email protected]"
  }
}

A mesma chave serve no envelope e no nome do arquivo, como Envelope {{order_id}} — {{person_name}}.

Anexando arquivos no próprio disparo (runner_files)

Se o step signature do flow declarar documents[].kind: "runner_files", você pode enviar o conteúdo do arquivo já no POST /execute, casando pelo key:

{
  "contact": { "phone_number": "5511999999999" },
  "files": [
    {
      "key": "1",
      "content_base_64": "data:application/pdf;base64,JVBERi0xLjQK..."
    }
  ]
}

Acompanhar

GET /api/v1/executions/{execution_id} — retorna o registro consolidado (status, current_step, files[] com URL temporária de leitura e, no canal web, web_url).

GET /api/v1/executions/{execution_id}/steps — retorna o histórico de etapas já executadas.

Quem enviou callback_url no disparo também recebe o andamento por webhook. O formato está em Webhooks.

Cancelar

POST /api/v1/executions/{execution_id}/cancel — idempotente sobre uma execução já cancelada (responde 200 de novo, sem novo evento); responde 409 se a execução já estiver em outro estado terminal (completed/failed). A etapa que estava em andamento também passa a canceled. No WhatsApp, se essa etapa era form, verify ou kyc, o contato recebe a mesma mensagem de falha usada quando a etapa falha por outro motivo. Em api e web, nada é enviado.

📍 Endpoints

Referência completa, com Try It!: Executor (Runner).

🔒 Autenticação

Header Authorization com o UUID do access_token (sem Bearer) — mesmo token usado no Orquestrador. Para obter o token, veja Access token.

Próximo passo ➡️

• Módulos — entenda o papel de cada capacidade acionada pela esteira.
• Collections — teste os endpoints do Executor em Postman, Insomnia ou Bruno.
• FAQ: dúvidas em ClickFlow — respostas curtas para as dúvidas mais comuns.