Saltar para o conteúdo principal
POST
cURL
Use este endpoint para criar questionários simples através da API. Envie um array form_elements pela ordem em que os utilizadores devem responder às perguntas. A Didit cria por si o grafo interno do questionário. A API suporta apenas questionários lineares simples. Não envie graph, branches, next nem regras condicionais.

Campos obrigatórios

  • title é o nome interno do questionário.
  • languages tem de incluir en.
  • form_elements tem de conter pelo menos uma pergunta.
  • Cada elemento de formulário precisa de um element_type e de um label traduzido.
Também pode adicionar a um elemento de formulário uma description traduzida, opcional, como texto de ajuda. Está disponível em todos os tipos de elemento, exceto separator, e é devolvida como description do item no relatório do questionário.

Tipos de elementos

Use valores em minúsculas, como short_text, multiple_choice, email, file_upload ou date_picker. Também são aceites valores em maiúsculas, como SHORT_TEXT. Para dropdown, single_choice e multiple_choice, adicione options. Se omitir o value de uma opção, a Didit gera um a partir do rótulo.

Validação de campos

Adicione um objeto validation, opcional, a um elemento short_text, long_text ou number para impor um formato à resposta do utilizador. É útil para identificadores com formatos rigorosos, como números de identificação fiscal, números de identificação nacional ou números de cartão. A validação é executada enquanto o utilizador preenche o campo (o utilizador não pode avançar até o valor passar na validação) e é novamente aplicada pela API no envio.
A resposta inclui questionnaire_id. Guarde-o, porque o vai usar como questionnaire_uuid quando adicionar o questionário a um fluxo.

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json

Crie um questionário linear simples. A API converte form_elements no grafo interno do questionário.

title
string
obrigatório

Nome interno do questionário.

languages
string[]
obrigatório

Idiomas incluídos em cada rótulo. Tem de incluir en.

Exemplo:
form_elements
object[]
obrigatório

Perguntas na ordem exata em que os utilizadores as devem ver. Ramificações e campos condicionais não são suportados.

Minimum array length: 1
description
string | null
default_language
string

Idioma predefinido. Tem de estar incluído em languages.

Exemplo:

"en"

is_active
boolean
padrão:true
status
enum<string>

Omita este campo para criar um questionário publicado pronto para fluxos.

Opções disponíveis:
draft,
published

Resposta

Questionário criado. A resposta inclui o questionnaire_id — guarde-o para referenciar este questionário em fluxos ou em futuras chamadas de atualização/eliminação.

Detalhe completo do questionário retornado pelos endpoints GET, POST (criar) e PATCH (atualizar).

questionnaire_id
string<uuid>

Identificador único do questionário. Utilize este id ao referenciar o questionário a partir de um fluxo ou em pedidos subsequentes de atualização/eliminação.

title
string
description
string | null
languages
string[]
default_language
string
is_active
boolean
is_simple_questionnaire
boolean
graph
object

Estrutura em grafo com start_node e mapa de nós.

sections
object[]

Conteúdo do questionário agrupado em secções (derivado do grafo).

questionnaire_group_id
string<uuid>

Identificador estável que agrupa todas as versões do mesmo questionário.

version
integer
status
enum<string>
Opções disponíveis:
draft,
published
published_at
string<date-time> | null
is_editable
boolean

True quando o questionário ainda pode ser editado no local (versões de rascunho).

Última modificação em 7 de novembro de 2026