Skip to main content
Tudo o que a tela Ajustes → Formulários faz cabe em um endpoint só. Ele cria e edita a definição do formulário: os campos, os tipos, a ordem e as condicionais.
Exige a permissão dynamic_forms.edit. Sem ela, a resposta é 403 com message: "permission_required".
Este endpoint não grava respostas. Responder um formulário é outro endereço, e depende de saber onde o formulário está anexado — ver Formulários dinâmicos e o pivot.
O salvamento substitui o formulário inteiro. Não existe “adicionar um campo”: cada chamada descreve o formulário completo, e todo campo ativo que ficar de fora do payload é apagado em definitivo — junto com as respostas que já tinham sido dadas nele.Quem edita pela API precisa sempre ler o formulário atual, alterar e reenviar tudo. Ver O que o salvamento apaga.

​
O corpo da requisição

​
O campo

Cada item de edges é um campo do formulário.
Envie index em todos os campos, sempre. A coluna tem 0 como padrão e o servidor não atribui posição sozinho. Um payload sem index grava o formulário inteiro na posição 0, e a ordem que aparece para quem preenche passa a ser arbitrária.
custom_validation é o padrão sem delimitadores — escreva ^[0-9]{5}-[0-9]{3}$, não /^[0-9]{5}-[0-9]{3}$/. Uma expressão inválida devolve 422.

​
Campo novo ou campo existente

É o id que decide, e ele tem três formas: O texto é descartado depois de salvar — ele só existe durante a requisição, para ligar uma condicional a um campo que ainda não tem número.
Dê a cada campo novo um id de texto único. Dois campos novos sem id colidem na tabela de referências, e as condicionais de um deles se perdem sem erro nenhum. O mesmo vale para dois campos novos com o mesmo texto.

​
Os tipos de campo

São 21. O nome na tabela é o valor literal de type.
Os três primeiros exigem options. matrix exige options em outro formato.
Estes quatro, mais counter, não funcionam em publicação de formulário — quem responde de fora não tem acesso aos registros da conta.
O arquivo em si sobe por outro endpoint, antes da resposta. Ver Anexos em resposta de formulário.

​
As opções

options muda de formato conforme o tipo.
Uma lista simples de textos:
Omitir options em um campo de escolha já existente apaga as respostas dele. O servidor limpa toda resposta que não esteja na lista recebida, e uma lista ausente é tratada como lista vazia. O campo continua com as opções antigas, mas as respostas somem.O mesmo mecanismo age quando você remove uma opção de propósito: quem tinha respondido aquele valor fica sem resposta.

​
Campo matriz

O tipo matrix monta uma grade: cada linha é uma pergunta, cada coluna é um dado a preencher. É o formato de escala Likert e de avaliações item a item.
Colunas também aceitam required, description e help_text.
O type de uma coluna que já existe não pode ser trocado. A troca devolve 422. Para mudar o tipo, remova a coluna e crie outra com key diferente — lembrando que remover a coluna descarta o que já foi respondido nela.
A resposta de uma matriz é um objeto aninhado por chave: {"atend": {"nota": "Bom", "obs": "..."}}.

​
Condicionais

A condicional fica no campo afetado — o que aparece ou some —, e não no campo que decide. Cada regra tem três partes: Os operadores disponíveis:
Envie value em todas as regras. Em is_empty e is_not_empty o valor é ignorado, mas o atributo precisa estar presente — mande "". Uma regra sem value derruba a requisição com erro de servidor, não com 422.
As condicionais são substituídas inteiras a cada salvamento, campo a campo. Omitir conditionals em um campo que tinha regras remove todas elas.
Um campo matrix não pode ser o target_id de uma condicional — a resposta dele é uma grade, não um valor comparável. A tentativa devolve 422 com form_edge_conditional_target. A matriz pode, sim, ser o campo afetado.
Obrigatoriedade e regex não são verificadas no servidor em campos que têm condicional — a checagem fica só na interface. Ver Criar um formulário.

​
O que o salvamento apaga

Este é o ponto que separa uma integração segura de uma que destrói dados.
Campo ativo que não aparece no payload é apagado em definitivo — não vai para a lixeira. As respostas dele são apagadas junto, por cascata no banco, em todos os lugares onde o formulário está anexado. Não há como desfazer.
O fluxo correto para qualquer edição pela API é sempre o mesmo:
1

Leia o formulário atual

com { "form_id": 19 }. A resposta traz o formulário com todos os campos, inclusive os arquivados, e as condicionais de cada um.
2

Altere o que precisa

Mexa na cópia que você recebeu. Campos novos entram com id em texto; campos existentes mantêm o id numérico.
3

Reenvie tudo

com o formulário completo — title incluído, index em cada campo, e os campos que você não quis mexer exatamente como vieram.
O objeto devolvido por get-form já tem a forma que save-form espera. Ler, alterar a cópia e devolver é o caminho mais curto e o mais seguro.

​
Arquivar em vez de apagar

Quando um campo sai do formulário mas as respostas antigas precisam continuar existindo, use action:
Um campo arquivado precisa continuar no payload de todo salvamento seguinte. Ele não some do formulário — some da tela de quem preenche. Se você parar de enviá-lo, ele é tratado como campo removido e é apagado junto com as respostas que você queria preservar.Como get-form devolve os arquivados, o fluxo de ler-alterar-reenviar já cuida disso sozinho.
Em um campo com action, os outros atributos são ignorados: arquivar e restaurar não alteram rótulo, tipo nem opções.

​
Exemplos

Um formulário novo, com um campo só:

​
Erros comuns

title é obrigatório em toda chamada, inclusive quando você só quer mexer nos campos. Reenvie o título atual.
O target_id de uma condicional não bate com nada: nem com um campo existente do formulário, nem com o texto de referência de um campo novo da mesma requisição.Confira se o texto está idêntico nos dois lugares — ele diferencia maiúsculas e minúsculas.
Uma condicional aponta para um campo matrix. Escolha outro campo como critério.
value veio com um tipo que não dá para comparar. Aceita texto, número, null ou uma lista de textos e números.
O token não tem dynamic_forms.edit. Anexar formulário a um objeto é outra permissão: frame_settings.edit.model_forms.
Faltou index. Sem ele todos os campos ficam na posição 0. Reenvie o formulário com a ordem explícita.

​
Próximos passos

Anexos em resposta de formulário

O upload que precede a resposta de um campo attachment.

Formulários dinâmicos e o pivot

Onde o formulário está anexado — e como gravar as respostas.

Criar um formulário

Os mesmos campos pela interface, com o que cada configuração faz.

Formulários dinâmicos

O conceito: um formulário sem dono, anexado a vários lugares.