Estrutura do formulário

Um Formulário (Form) é um container que agrupa campos de coleta de dados para ser utilizado em diversos contextos da plataforma. Cada formulário pode conter N campos de diferentes tipos.

{
  "id": "698b8a825eaf8de7c5af8de7",
  "name": "Formulário de Cadastro",
  "active": true,
  "community": "test",
  "createdAt": "2026-02-10T19:44:02.328Z",
  "updatedAt": "2026-02-12T20:46:11.133Z",
  "fields": [
    {
      "kind": "text",
      "name": "fullname",
      "caption": "Nome Completo",
      "required": true,
      "allowManuallyInput": false,
      "placeholder": "Digite seu nome completo",
      "format": "fullname"
    },
    {
      "kind": "text",
      "name": "email",
      "caption": "E-mail",
      "required": true,
      "allowManuallyInput": false,
      "placeholder": "seu@email.com",
      "format": "email"
    },
    {
      "kind": "enum",
      "name": "state",
      "caption": "Estado",
      "required": true,
      "allowManuallyInput": false,
      "choices": [
        {
          "name": "São Paulo",
          "value": "SP",
          "checked": false
        },
        {
          "name": "Rio de Janeiro",
          "value": "RJ",
          "checked": false
        }
      ]
    }
  ]
}

Campos principais

Campo	Tipo	Descrição
id	string	ID único do formulário
name	string	Nome descritivo do formulário
active	boolean	Indica se o formulário está ativo e disponível para uso (padrão: true)
community	string	Comunidade (tenant) do formulário
fields	array<object>	Lista de campos do formulário (ver abaixo)
createdAt	string (ISO 8601)	Data e hora de criação
updatedAt	string (ISO 8601)	Data e hora da última atualização

---

fields

Lista de campos que compõem o formulário. Cada campo tem um kind (tipo) que determina sua estrutura e validações específicas.

Campos base (presentes em todos os tipos)

Campo	Tipo	Descrição
kind	string	Tipo do campo. Valores possíveis: text, enum, set, checkbox, agreement, externalReference
name	string	Nome único do campo dentro do formulário (máx. 44 caracteres)
caption	string	Descrição legível do campo exibida ao usuário (máx. 120 caracteres)
required	boolean	Indica se o campo é obrigatório (padrão: false)
allowManuallyInput	boolean	Indica se permite entrada manual de dados além de outras fontes (padrão: false)

---

Tipos de campos

text

Campo de entrada de texto com validações opcionais.

{
  "kind": "text",
  "name": "email",
  "caption": "E-mail",
  "required": true,
  "allowManuallyInput": false,
  "placeholder": "seu@email.com",
  "format": "email"
}

Campo	Tipo	Descrição
placeholder	string | null	Texto de dica exibido no campo vazio. Caso não informado, null
format	string	Formato de validação do texto. Valores possíveis: fullname, document, cpf, email, none

Validações por formato:

• fullname: Valida se há pelo menos 2 nomes com 2+ caracteres cada
• cpf: Valida o CPF usando algoritmo de validação padrão
• email: Valida se segue formato de e-mail válido
• document: Aceita qualquer documento (aplicável em contextos genéricos)
• none: Sem validação específica

---

enum

Campo com lista de opções onde o usuário seleciona uma única opção (como radio button).

{
  "kind": "enum",
  "name": "state",
  "caption": "Estado",
  "required": true,
  "allowManuallyInput": false,
  "choices": [
    {
      "name": "São Paulo",
      "value": "SP",
      "checked": false
    },
    {
      "name": "Rio de Janeiro",
      "value": "RJ",
      "checked": true
    },
    {
      "name": "Minas Gerais",
      "value": "MG",
      "checked": false
    }
  ]
}

Campo	Tipo	Descrição
choices	array<object>	Array de opções disponíveis
choices[].name	string	Rótulo exibido da opção
choices[].value	string | null	Valor técnico da opção. Se não informado, usa o name
choices[].checked	boolean | null	Indica se é a opção padrão selecionada. Caso não informado, null

---

set

Campo com lista de opções onde o usuário pode selecionar múltiplas opções (como checkboxes).

{
  "kind": "set",
  "name": "interests",
  "caption": "Interesses",
  "required": false,
  "allowManuallyInput": false,
  "choices": [
    {
      "name": "Tecnologia",
      "value": "tech",
      "checked": false
    },
    {
      "name": "Educação",
      "value": "education",
      "checked": true
    },
    {
      "name": "Saúde",
      "value": "health",
      "checked": true
    }
  ]
}

Campo	Tipo	Descrição
choices	array<object>	Array de opções disponíveis para seleção múltipla
choices[].name	string	Rótulo exibido da opção
choices[].value	string | null	Valor técnico da opção. Se não informado, usa o name
choices[].checked	boolean | null	Indica se é uma opção padrão selecionada. Caso não informado, null

---

checkbox

Campo booleano simples (sem configurações adicionais).

{
  "kind": "checkbox",
  "name": "agree_terms",
  "caption": "Concordo com os termos e condições",
  "required": true,
  "allowManuallyInput": false
}

Campo	Tipo	Descrição
(sem campos específicos)	-	Usa apenas os campos base de FormField

---

agreement

Campo para aceitar termos ou acordos, podendo incluir mídia (imagem/documento).

{
  "kind": "agreement",
  "name": "privacy_policy",
  "caption": "Política de Privacidade",
  "required": true,
  "allowManuallyInput": false,
  "text": "Ao prosseguir, você concorda com nossa política de privacidade...",
  "media": {
    "url": "https://cdn.layers.digital/uploads/.../policy.pdf",
    "path": "/uploads/.../policy.pdf",
    "mime": "application/pdf",
    "width": null,
    "height": null,
    "size": 125480,
    "name": "policy.pdf",
    "orientation": null
  }
}

Campo	Tipo	Descrição
text	string	Texto do acordo/termo a ser aceito
media	object | null	Arquivo anexado ao acordo (imagem, PDF, etc.). Caso não informado, null
media.url	string | null	URL pública do arquivo. Caso não informada, null
media.path	string | null	Caminho interno do arquivo. Caso não informado, null
media.mime	string	Tipo MIME do arquivo. Ex: application/pdf, image/png
media.width	integer | null	Largura em pixels (para imagens). Caso não informada, null
media.height	integer | null	Altura em pixels (para imagens). Caso não informada, null
media.size	integer	Tamanho do arquivo em bytes
media.name	string	Nome do arquivo
media.orientation	string | null	Orientação da imagem (portrait/landscape). Caso não informada, null

---

externalReference

Campo que referencia dados de sistemas externos (como membros da comunidade).

{
  "kind": "externalReference",
  "name": "member_id",
  "caption": "Selecione um membro",
  "required": true,
  "allowManuallyInput": true,
  "format": "member"
}

Campo	Tipo	Descrição
format	string	Tipo de referência externa. Valor possível: member

---

Estados do Formulário

Estado	Descrição
active: true	Formulário ativo e disponível para uso
active: false	Formulário inativo (arquivado ou descontinuado)

---

Tipos de Campos Suportados

Tipo	Permite Múltiplas Seleções	Uso
text	Não	Captura texto com validações (nome, e-mail, documento, etc.)
enum	Não	Seleção simples de uma opção entre várias
set	Sim	Seleção de múltiplas opções
checkbox	Não	Confirmação de uma única condição booleana
agreement	Não	Aceitar termos/políticas com opção de anexar arquivo
externalReference	Não	Referência a dados externos (membros, etc.)