CLclicksign
executions

Inicia uma execução de fluxo

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.

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

Path parameters

flow_idstring required

Flow ID

Request body

callback_urlstring

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.

contextobject

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.

Example request

{
  "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": "joao@exemplo.com"
  }
}

Response

Created

callback_urlstring

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.

contextobject

Objeto livre injetado no POST /execute. Persistido no HEAD e usado na interpolação de envelope/signatários, forms e consent.

created_atstring
execution_idstring
flow_idstring
presentation_runner_errorobject
status'running' | 'completed' | 'failed' | 'canceled'

running | completed | failed | canceled

updated_atstring
web_urlstring

Link da execução na experiência web da Clicksign. Presente somente quando channel="web".

whatsapp_conclusion_outboundobject
whatsapp_presentation_outboundobject

Example response

{
  "callback_url": "https://api.cliente.com/webhooks/clickflow",
  "channel": "whatsapp",
  "current_step": {
    "id": "3",
    "type": "signature",
    "url": "https://app.clicksign.com/notarial/widget/signatures/uuid/redirect"
  },
  "status": "running",
  "web_url": "https://app.clicksign.com/app/flow-public/uuid"
}

Changes

No recorded changes to this operation across all 1 revision of this API.