ClickForm: coleta de dados

O ClickForm é o motor de coleta de dados da Clicksign, desacoplado da geração de documentos. Pode ser usado como o step form de um ClickFlow, ou de forma independente via API.

💾 Modelo de dados

3 níveis:

• Form — definição base e metadados (nome, callback_url).
• Version — estrutura imutável de campos e configurações visuais de uma versão do formulário.
• Run — uma instância de preenchimento único: gera o link do formulário, já com dados pré-preenchidos (context) e, opcionalmente, uma etapa de verificação de acesso.

O ClickForm é contratado e habilitado de forma independente da API v3 da Clicksign (Assinatura Eletrônica/Envelopes). Sua empresa ainda não tem o ClickForm habilitado? Fale com o nosso time comercial.

🔒 Autenticação

Header Authorization com o UUID do access_token (sem Bearer), obtido na página de configurações da API da Clicksign. Veja mais detalhes aqui.

🚀 Primeiros passos

1. Criar o formulário

POST /api/v1/forms

{
  "name": "Cadastro de cliente",
  "callback_url": "https://parceiro.exemplo.com/hooks/clickform"
}

Página de referência: Criar Formulário.

2. Criar uma versão (os campos)

POST /api/v1/forms/{form_key}/versions

{
  "settings": {
    "title": "Atualização de contato",
    "subtitle": "Por favor, confirme os dados de contato."
  },
  "fields": [
    { "label": "Nome completo", "type": "text", "required": true, "order": 1 },
    { "label": "Whatsapp", "type": "phone_number", "required": true, "order": 2 }
  ]
}

Página de referência: Criar Versão.

3. Criar um run (o link único de preenchimento)

POST /api/v1/versions/{version_key}/runs

{
  "context": {
    "nome-completo-59661f5fe933": { "value": "Maria da Silva", "read_only": false }
  }
}

A resposta traz form_url — o link único para o contato preencher. Página de referência: Criar Run.

4. Receber a resposta

Configure callback_url (no form ou no run) para receber um webhook quando o preenchimento for concluído — ou consulte GET /api/v1/versions/{version_key}/runs/{run_key} (campo responses).

5. Ambientes

Para saber mais sobre os ambientes, acesse este tutorial. Abaixo, as URLs a serem utilizadas:

✅ Checklist de sucesso

• Guardei o form_key e o version_key retornados?
• O context do run usa as mesmas key dos campos da versão?
• Configurei callback_url para não depender de polling?

Próximo passo ➡️

• Criar e utilizar formulários — todos os tipos de campo, condições e verificação de acesso.
• Collections — Postman, Insomnia e Bruno prontos para testar o ClickForm.