ClickFlow: orquestração de jornadas transacionais

Esta página é o passo a passo da integração. Se você quer entender a jornada antes de chamar a API, comece por Como funciona o ClickFlow. Se ainda está decidindo se o produto serve, volte para a Introdução ao ClickFlow. O que está abaixo basta para autenticar, criar, publicar e disparar sem passar por aquela página.

O ClickFlow é a esteira de automação da Clicksign: ele orquestra, em uma sequência linear e configurável, os módulos que compõem uma jornada de contratação (Módulo de Aceite, Módulo de Coleta de Dados (ClickForm), Módulo de Autenticação, Módulo de KYC e Módulo de Assinatura), entregando a experiência ao consumidor final via WhatsApp, API ou web.

A arquitetura é dividida em duas peças com responsabilidades bem separadas:

Cada módulo (Módulo de Coleta de Dados (ClickForm)/form, Módulos de Aceite e de Notificação/consent, Módulo de Autenticação/verify, Módulo de KYC/kyc, Módulo de Assinatura/signature ou embedded_signature) é uma unidade de execução independente — o Orquestrador só sabe orquestrar steps, não conhece a lógica interna de cada módulo.

🔒 Autenticação

Todas as rotas de /api/v1 (Orquestrador e Executor) exigem o header Authorization com o UUID do access_token — sem prefixo Bearer. Para obter o token, siga o passo a passo em Access token.

Teste de autenticação

Para confirmar que o token está válido, liste os flows no sandbox do Orquestrador:

curl --request GET \
  --url https://clickflow-sandbox.clicksign.com/api/v1/flows \
  --header "Authorization: $access_token"

Uma conta sem flows ainda responde 200 com uma lista vazia:

[]

Token ausente ou inválido responde 401:

{
  "error": "authorization required"
}

🚀 Primeiros passos

1. Criar um flow (draft)

POST /api/v1/flows no Orquestrador. Um flow é uma lista ordenada de steps — cada um com um type (acceptance, form, verify, kyc, signature, embedded_signature, consent) e um context específico daquele tipo.

{
  "name": "Proposta Crédito — form",
  "steps": [
    {
      "type": "form",
      "context": {
        "version_key": "sua-form-version-key"
      }
    }
  ]
}

O que cada tipo de etapa faz, e o que muda o desfecho, está em Módulos. O schema de cada context está no Orquestrador. Página de referência: Criar Flow.

2. Publicar o flow

Um flow criado nasce em draft — precisa ser publicado antes de aceitar execuções. Flow published não aceita edição. Para alterar, despublique, edite e publique de novo. Uma execução já iniciada segue a definição com que começou. unpublished volta a ser editável e não aceita disparo novo até ser publicado outra vez. Remover o flow é exclusão lógica: o status passa a deleted.

Endpoint: PATCH /api/v1/flows/{id}/publish

Página de referência: Publicar Flow.

3. Iniciar uma execução

Com o flow publicado, dispare uma execução informando o contato — essa chamada é feita no Executor (Runner), não no Orquestrador.

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

{
  "contact": {
    "person_name": "Maria da Silva",
    "person_email": "[email protected]",
    "phone_number": "5511999999999"
  }
}

person_email é opcional. É mais um dado do contato da execução, ao lado do nome, do documento, da data de nascimento e do telefone.

O mesmo disparo aceita context, um objeto com dados que a empresa já tem. O flow declara {{chave}} e a execução preenche: o cliente da esteira, um signatário extra, o nome do envelope, o arquivo e a mensagem. O exemplo está em Injetar dados no flow.

Canais

O channel é escolhido neste disparo. A definição do flow não guarda canal. Para a pessoa que percorre a jornada:

WhatsApp exige phone_number. Em api e web, o telefone é opcional, salvo quando a jornada tem uma etapa que usa WhatsApp. acceptance sempre dispara no WhatsApp e falha sem telefone. consent também manda a mensagem inicial no WhatsApp em qualquer canal e exige telefone. Sem expiration_time, o prazo desse aceite é de 2 horas. A comparação do que o contato vê em cada canal está em Os três canais.

Página de referência: Iniciar Execução.

4. Acompanhar a execução

Endpoint: GET /api/v1/executions/{execution_id} (disponível tanto no Orquestrador quanto no Executor — o Executor devolve o estado consolidado, incluindo os arquivos anexados). Os status são running (numa etapa), waiting (aguarda o retorno de um módulo), completed (todas as etapas terminaram), failed (uma etapa encerrou a jornada) e canceled (cancelamento definitivo). O detalhe do cancelamento está no Orquestrador.

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

Página de referência: Estado da Execução.

5. Ambientes

O sandbox está liberado para testes. Produção exige o ClickFlow contratado. Para saber mais sobre os ambientes, acesse este tutorial. Abaixo, as URLs a serem utilizadas:

✅ Checklist de sucesso

• Recebi o flow_id ao criar o flow?
• O flow está published antes de tentar executar?
• Escolhi o channel certo para o meu caso (whatsapp, api ou web)?

Próximo passo ➡️

• Introdução ao ClickFlow — o que o produto resolve e para quem serve.
• Como funciona o ClickFlow — o que o produto é, para quem ainda não conhece.
• Orquestrador — todos os tipos de step, ciclo de vida do flow e da execução.
• Executor — canais whatsapp, api e web, upload de arquivos, cancelamento.
• Módulos — regras de cada capacidade usada nas etapas.
• Webhooks — avisos dos módulos ao longo da jornada.
• Collections — Postman, Insomnia e Bruno prontos para testar o Orquestrador e o Executor.
• FAQ: dúvidas em ClickFlow — respostas curtas para as dúvidas mais comuns.