---
title: "Inicia uma execução de fluxo"
method: POST
path: "/api/v1/flows/{flow_id}/execute"
tags: ["executions"]
---

# Inicia uma execução de fluxo

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

## Request

- Base URL: `https://clickflow-runner-sandbox.clicksign.com`
- URL: `https://clickflow-runner-sandbox.clicksign.com/api/v1/flows/{flow_id}/execute`
- Auth: API key in header `Authorization`

Cria uma execução no orquestrador e persiste o estado inicial no Runner. O Authorization desta requisição (access_token) é repassado ao orquestrador, que o introspecciona para identificar a conta dona do flow.

**Canal `whatsapp` (padrão):** Runner envia mensagens automáticas via WhatsApp — apresentação, links de form/verify/signature e conclusão. `contact.phone_number` é obrigatório.

**Canal `api`:** Runner não envia mensagens automáticas. A resposta inclui `current_step.url` com o link do passo atual para o cliente entregar ao contato. `contact.phone_number` é opcional. Exceção: steps `acceptance` sempre enviam WhatsApp (interação funcional) e falham se o contato não tiver phone_number.

**Canal `web`:** mesmo comportamento de `api`. A resposta também inclui `web_url`, o link da execução na experiência web da Clicksign.

## Path parameters

- `flow_id` string, required

## Request body

- object
  - `callback_url` string: URL https opcional para receber o webhook de saída do Flow (execution.started, step.started, step.finished, execution.finished). Precisa ser URL absoluta https, com host e sem usuário ou senha na URL. Endereço de loopback, rede privada, link-local (incluindo metadata de nuvem), não especificado ou multicast é recusado. URL inválida retorna 400 sem criar a execução. Sem o campo, nenhum evento é emitido. Cada evento sai uma vez; falha de entrega não interrompe a execução. O corpo traz event_id, event, occurred_at e execution no mesmo formato do GET da execução.
  - `channel` 'whatsapp' | 'api' | 'web': Canal de comunicação da execução. "whatsapp" (padrão, compatível com versões anteriores): Runner envia mensagens automáticas via WhatsApp em todas as etapas — apresentação, steps form/verify/signature e conclusão. contact.phone_number é obrigatório. "api": Runner não envia mensagens automáticas. O cliente é responsável por entregar os links ao contato. A resposta inclui o objeto current_step com id, type e url do passo em andamento. contact.phone_number é opcional (exceto para steps acceptance, que sempre exigem WhatsApp). "web": mesmo comportamento de "api", mais o campo web_url na resposta com o link da execução na experiência web da Clicksign. Omitir o campo equivale a "whatsapp". Qualquer outro valor retorna 400.
  - `contact` object
    - `person_birthday` string
    - `person_documentation` string
    - `person_email` string: E-mail opcional da pessoa da execução. Quando preenchido, o Executor repassa o valor à etapa de Assinatura.
    - `person_name` string
    - `phone_number` string
  - `context` object: Objeto livre injetado no disparo pelo sistema chamador (dados do próprio sistema). Persistido no HEAD da execução e usado na interpolação de envelope/signatários, pré-preenchimento de formulários ({{chave}} em context_map_keys) e variáveis de consent. Na mesma chave, o contact vence este context, e este context vence a resposta de um formulário anterior. Tamanho máximo após JSON: 150 KiB; acima disso retorna 400 sem criar a execução. O body HTTP do POST /execute, incluindo files[], tem teto de 16 MiB; acima disso a execução também não é criada.
  - `files` object[]: Arquivo(s) enviados em base64 no próprio disparo. Opcional (aditivo) — sem este campo, o comportamento atual é mantido. Cada item tem content_base_64 (data-URL completa, ex.: "data:application/pdf;base64,...") e key — o step signature do fluxo declara documents[].kind "runner_files" com o mesmo key pra casar o conteúdo com o slot certo (nome do arquivo é definido no fluxo, não aqui).
    - `content_base_64` string
    - `key` string

## Response `201`

Created

- object
  - `account` object
    - `id` integer
    - `key` string
    - `name` string
  - `callback_url` string: URL de callback informada no disparo, devolvida para conferência. Ausente quando o disparo não informou callback_url.
  - `channel` 'whatsapp' | 'api' | 'web': Canal definido no POST /execute. "whatsapp": Runner gerencia envio de mensagens. "api": o integrador entrega os links. "web": a Clicksign entrega a jornada pelo link web da execução.
  - `contact` object
    - `person_birthday` string
    - `person_documentation` string
    - `person_email` string: E-mail opcional da pessoa da execução. Quando preenchido, o Executor repassa o valor à etapa de Assinatura.
    - `person_name` string
    - `phone_number` string
  - `context` object: Objeto livre injetado no POST /execute. Persistido no HEAD e usado na interpolação de envelope/signatários, forms e consent.
  - `created_at` string
  - `current_step` object: Passo em andamento. Presente somente quando channel="api" ou "web" e há step RUNNING. Permite ao cliente saber qual URL entregar ao contato sem precisar consultar os steps.
    - `id` string: ID do step no orquestrador
    - `type` 'form' | 'verify' | 'signature' | 'embedded_signature' | 'acceptance': Tipo do step: form | verify | signature | embedded_signature | acceptance
    - `url` string, nullable: Link para o contato acessar. null para acceptance.
  - `execution_id` string
  - `files` object[]: Arquivos enviados em base64 no disparo (files[]), já materializados no bucket próprio do Runner — expõe só a key de correlação e uma URL temporária de leitura, nunca bucket/S3 key internos nem o conteúdo.
    - `error` string: Error vem preenchido (mensagem genérica, sem detalhe interno) quando o presign desse arquivo falha — o cliente sabe distinguir "sem URL por erro transitório" de um eventual item sem URL por outro motivo, em vez de silêncio.
    - `key` string
    - `url` string
  - `flow_id` string
  - `presentation_runner_error` object
  - `status` 'running' | 'completed' | 'failed' | 'canceled': running | completed | failed | canceled
  - `updated_at` string
  - `web_url` string: Link da execução na experiência web da Clicksign. Presente somente quando channel="web".
  - `whatsapp_conclusion_outbound` object
  - `whatsapp_presentation_outbound` object

## Other responses

- `400`: Bad Request
- `500`: Internal Server Error

---

[API](https://skmtc.dev/clicksign/apis/clickflow-runner-api.md) - [All operations](https://skmtc.dev/clicksign/apis/clickflow-runner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clicksign/apis/clickflow-runner-api/revisions/f5ee0b7db692?raw)