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",
    "phone_number": "5511999999999",
    "person_documentation": "52998224725",
    "person_birthday": "1990-05-06"
  }
}

O parâmetro channel

Exceção: steps acceptance sempre disparam WhatsApp (é uma interação funcional) e falham sem phone_number, mesmo em channel: api.

Contexto no disparo (context)

Objeto opcional, chave-valor livre, para dados que o seu sistema já tem (CPF do cônjuge, parâmetros da esteira, etc.). Entra no resolvedor de placeholders ({{chave}}): interpolação de envelope/signatários, pré-preenchimento de formulário via context_map_keys e variáveis de consent. É 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. Omitir o campo mantém o comportamento anterior.

{
  "contact": { "phone_number": "5511999999999" },
  "context": {
    "cpf_conjuge": "52998224725",
    "produto": "auto"
  }
}

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).

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

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).

📍 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.