Crie um formulário, passo a passo

O que você precisa saber

1. Entenda para que serve o formulário, quem vai preencher e o que vai ser feito com as respostas.
2. create_form (ou get_form, para um formulário que já existe) retorna a definição completa e a draft_revision dela.
3. Edite a definição completa e salve com save_form_draft, enviando a revisão atual em base_revision e um UUIDv7 novo em mutation_id.
4. Confira os issues no retorno. Corrija e salve de novo até a lista ficar vazia.
5. Mostre o resultado ao usuário. Só chame publish_form quando ele pedir, passando a revisão que ele conferiu.

Antes de começar

Pergunte ao usuário, ou descubra pela conversa:

• O objetivo. Para que decisão ou tarefa as respostas vão servir? Corte toda pergunta que não ajude nisso.
• Quem vai responder. Um cliente no celular, um colega, um convidado? Isso define o tom e o tamanho do formulário.
• O que é obrigatório. Torne obrigatórias só as respostas de que o usuário realmente precisa.
• O que acontece depois. A tela final deve dizer a quem responde o que esperar.

Se o formulário for longo ou tratar de um assunto sensível, liste as perguntas no chat e peça a confirmação do usuário antes de salvar.

Crie o formulário

Chame create_form com um nome. O form do retorno traz o id, a draft_revision (1 em um formulário novo), a definition e os issues atuais.

Todo formulário novo vem com uma tela de boas-vindas, uma pergunta de texto curto sem título, uma tela final de agradecimento e um tema branco. Os issues dele pedem o título que falta na pergunta. Troque essa pergunta inicial pela sua ou reaproveite o ID dela na sua primeira pergunta: nada depende dela ainda.

create_form não é idempotente. Se o retorno se perder, chame list_forms e procure o formulário antes de criar outro.

Para alterar um formulário que já existe, encontre-o com list_forms e leia com get_form.

Edite a definição

• Parta da definição que você acabou de ler. Mantenha todas as chaves principais, inclusive schemaVersion, mediaDefaults, theme e settings, e todos os IDs existentes. Veja A definição do formulário.
• Escreva as perguntas em fields, na ordem em que vão aparecer para quem responde. Comece cada uma pelo modelo do tipo em Tipos de pergunta ou em list_field_types e depois dê um título a ela.
• Dê um ID novo a cada pergunta, opção, linha, regra e cálculo que você criar: um UUIDv7 em minúsculas, único no formulário. Se não conseguir gerar, chame list_field_types com id_count e use os IDs retornados. Detalhes em Identificadores.
• Títulos e descrições são texto formatado, não strings simples. Veja Texto formatado.
• Para mudar o tipo de uma pergunta, substitua-a por uma nova, com ID novo, e atualize as regras, os cálculos e as referências de resposta que apontavam para o ID antigo.
• Use a configuração nextButton da última pergunta para dar ao botão um texto como "Enviar". Não existe um botão de envio separado.

Uma definição completa, pronta para publicar:

A referência técnica a seguir é gerada a partir do código e está em inglês, como os assistentes de IA a leem.

Contact request. The smallest useful form: three required questions, and an ending that greets the person by the name they typed.

It shows:

• required questions
• placeholder and maxLength settings
• an answer piped into the ending

{
    "schemaVersion": 2,
    "mediaDefaults": {
        "assetId": null,
        "layout": "above",
        "altText": ""
    },
    "welcome": {
        "enabled": true,
        "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Get in touch"}]}]},
        "description": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Three quick questions. We reply within one working day."}]}]},
        "button": "Start"
    },
    "ending": {
        "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Thanks, "},{"type":"answerToken","attrs":{"source":"answer","ref":"01990000-0000-7000-8000-000000000001","fallback":"there"}},{"type":"text","text":"!"}]}]},
        "description": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"We will reply to your email within one working day."}]}]}
    },
    "fields": [
        {
            "id": "01990000-0000-7000-8000-000000000001",
            "kind": "short_text",
            "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"What is your name?"}]}]},
            "description": {"type":"doc","content":[{"type":"paragraph","content":[]}]},
            "required": true,
            "options": [],
            "rows": [],
            "settings": {"nextButton":"Next","placeholder":"Jane Smith"},
            "media": {"inherit":true,"assetId":null,"layout":"above"}
        },
        {
            "id": "01990000-0000-7000-8000-000000000002",
            "kind": "email",
            "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"What is your email address?"}]}]},
            "description": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"We only use it to reply to this message."}]}]},
            "required": true,
            "options": [],
            "rows": [],
            "settings": {"nextButton":"Next"},
            "media": {"inherit":true,"assetId":null,"layout":"above"}
        },
        {
            "id": "01990000-0000-7000-8000-000000000003",
            "kind": "long_text",
            "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"How can we help?"}]}]},
            "description": {"type":"doc","content":[{"type":"paragraph","content":[]}]},
            "required": true,
            "options": [],
            "rows": [],
            "settings": {"nextButton":"Send message","maxLength":2000},
            "media": {"inherit":true,"assetId":null,"layout":"above"}
        }
    ],
    "theme": {
        "preset": "paper",
        "background": "#ffffff",
        "foreground": "#111827",
        "primary": "#2563eb",
        "buttonText": "#ffffff",
        "font": "Inter",
        "radius": 12,
        "density": "comfortable",
        "logoAssetId": null,
        "backgroundAssetId": null
    },
    "settings": {
        "allowReanswer": true,
        "hiddenFields": [],
        "fillLimit": null
    },
    "rules": [],
    "calculations": []
}

Salve o rascunho

Chame save_form_draft com:

O retorno traz a nova revision, os issues, o saved_at e o published_version_id. Use a revision como base_revision no próximo salvamento.

Se a rede falhar e você não souber se o salvamento passou, reenvie exatamente a mesma requisição, com o mesmo mutation_id. O trulyform devolve o resultado original em vez de salvar duas vezes. Já um mutation_id reaproveitado com outro conteúdo é recusado.

Quando o salvamento é recusado

• validation_failed com errors: a definição está com o formato errado, por exemplo uma chave desconhecida, um ID inválido ou um título em string simples. Nada foi salvo. Corrija os caminhos indicados em errors e salve de novo com a mesma base_revision e um mutation_id novo. As mensagens estão explicadas em Limites e erros.
• draft_conflict: existe um rascunho mais recente, talvez porque o usuário está editando o formulário no trulyform. Chame get_form, aplique sua alteração na definição retornada e salve com a draft_revision dela. Nunca sobrescreva o rascunho mais recente com uma cópia antiga.

Corrija os problemas

O salvamento funciona mesmo que o formulário ainda não esteja pronto para publicar. Os issues do retorno listam o que ainda impede a publicação:

{
    "nodeId": "01990000-0000-7000-8000-000000000001",
    "path": "title",
    "message": "Write your question.",
    "severity": "error"
}

nodeId é o ID da pergunta, regra ou cálculo com problema, ou então form, theme, welcome ou ending. Cada problema também tem um campo docs com a seção da documentação que o explica; passe esse valor para read_docs. Corrija todos os problemas e salve de novo. Os mais comuns estão em Problemas de publicação.

Revise com o usuário

Antes de publicar, resuma o formulário em linguagem simples: as perguntas em ordem, quais são obrigatórias e o que a lógica faz ("Se a pessoa escolher Presencial, perguntamos sobre restrições alimentares"). Passe ao usuário o editor_url do formulário, que vem em create_form, get_form ou list_forms. O link abre o formulário no editor do trulyform, onde ele pode pré-visualizar tudo exatamente como quem responde vai ver e fazer alterações por conta própria.

Publique

Chame publish_form com o form_id e a revision que o usuário conferiu, e só depois que ele pedir para publicar. O retorno traz a public_url para compartilhar.

• Se o rascunho mudou depois dessa revisão, a publicação falha com draft_conflict. Antes, mostre o rascunho mais recente ao usuário.
• Se o rascunho ainda tiver problemas, a publicação falha com validation_failed e a lista de issues.
• Publicar de novo o mesmo conteúdo não cria uma versão nova.
• As respostas já recebidas continuam ligadas à versão em que foram respondidas.
• Um formulário fechado continua fechado. Para reabrir, o usuário usa Reabrir formulário no trulyform.

Dicas para um bom formulário

• Seja breve. A maioria dos formulários precisa de menos de dez perguntas. Cada pergunta a mais significa menos respostas.
• Uma ideia por pergunta, em linguagem simples. Texto de ajuda vai na descrição, não no título.
• Escolha o tipo certo para cada resposta. Use email para e-mails, dropdown para listas longas, como países, single_choice para poucas opções, opinion_scale ou nps para avaliações e consent para aceites. Uma resposta number aceita decimais; para quantidades inteiras, como o número de convidados, use uma pergunta de escolha.
• Use lógica em vez de perguntas do tipo "Se sim…", para que cada pessoa veja só o que vale para ela.
• Use a tela de boas-vindas para explicar para que serve o formulário e quanto tempo leva. Em formulários bem curtos, desative-a.
• Use a tela final para agradecer e dizer o que acontece depois. Chamar a pessoa pelo nome, com uma referência de resposta, deixa tudo mais pessoal.