Introdução

Gerencie envios de formulários e recupere dados de formulários.

🎯 O que este módulo faz?

O módulo FormData permite que você envie formulários preenchidos pelo usuário (formulários de contato, pesquisas, registros) para o OneEntry e recupere os dados enviados para análise, relatórios e gerenciamento.

Pense nisso como seu gerenciador de envios de formulários - os usuários enviam formulários, você os armazena no OneEntry e os recupera sempre que precisar visualizar respostas, gerar relatórios ou analisar dados.

---

📖 Explicação Simples

Imagine que você tem um formulário de contato em seu site. Quando os usuários o preenchem:

1. Enviar - O usuário clica em "Enviar" → Os dados do formulário vão para o OneEntry
2. Armazenar - O OneEntry salva a submissão (nome, e-mail, mensagem)
3. Recuperar - Você busca as submissões para visualizar, exportar ou analisar
4. Gerenciar - Filtrar, pesquisar e organizar as respostas do formulário

Fluxo de trabalho no mundo real:

Usuário preenche o formulário de contato → postFormsData() → Salvo no OneEntry
                                                              ↓
Admin vê as submissões ← getFormsData() ← OneEntry retorna os dados

O que você pode fazer:

• 📤 Enviar formulários - Enviar dados preenchidos pelo usuário para o OneEntry
• 📥 Ver submissões - Obter todas as respostas do formulário com paginação
• 🔍 Pesquisar submissões - Encontrar submissões específicas por marcador ou filtro
• 📊 Exportar dados - Recuperar submissões para relatórios e análises
• 📧 Gerenciar respostas - Acompanhar envios de formulários em um só lugar

Cenários de exemplo:

Cenário	O que Acontece
Formulário de Contato	O usuário envia → Você recebe notificação por e-mail → Visualiza no painel
Pesquisa	Coletar respostas → Exportar para CSV → Analisar resultados
Registro	O usuário se inscreve → Dados armazenados → Enviar e-mail de confirmação
Feedback	O cliente deixa feedback → A equipe revisa → Responder ao cliente

---

✨ Conceitos Chave

O que são Dados de Formulário?

Dados de formulário são as informações que os usuários enviam através de formulários.

Estrutura de Submissão de Formulário

Cada submissão no OneEntry tem:

  const body: IBodyPostFormData = {
    formIdentifier: 'contact_form', // Marcador do formulário
    formModuleConfigId: 9,          // ID da configuração do módulo
    moduleEntityIdentifier: 'blog', // Identificador da entidade do módulo
    replayTo: null,                 // Endereço de e-mail para resposta
    status: 'sent',                 // Status da submissão
    formData: [                     // Campos do formulário
      {
        marker: 'string',           // Marcador do campo
        type: 'string',             // Tipo do campo
        value: 'Teste',             // Valor do campo
      },
      {
        marker: 'number',
        type: 'integer',
        value: 1,
      },
    ]
  };

Ciclo de Vida dos Dados de Formulário

1. O usuário preenche o formulário no navegador
   ↓
2. O frontend valida a entrada
   ↓
3. postFormsData() envia para o OneEntry
   ↓
4. O OneEntry valida e armazena a submissão
   ↓
5. Notificações enviadas (e-mail, webhook)
   ↓
6. O admin recupera com getFormsData()
   ↓
7. Revisar, exportar ou responder

Casos de Uso Comuns

Caso de Uso	Descrição	Exemplo
Formulários de Contato	Clientes entram em contato com perguntas	A equipe de suporte revisa e responde
Geração de Leads	Coletar informações de potenciais clientes	A equipe de vendas faz follow-up
Pesquisas	Coletar feedback e opiniões	O marketing analisa os resultados
Registros	Inscrever-se em eventos, newsletters	Acompanhar participantes/inscritos
Candidaturas a Emprego	Coletar currículos e cartas de apresentação	RH revisa candidatos
Formulários de Feedback	Satisfação do cliente e avaliações	Melhorar produtos/serviços

---

📋 O que você precisa saber

Enviar Formulários Requer Configuração

Antes de enviar, você precisa:

1. Marcador do formulário - Identificador único do formulário
2. ID da configuração do módulo do formulário - Das configurações do formulário
3. Identificador da entidade do módulo - Da configuração do formulário

Como obter esses:

// Buscar formulário
const form = await Forms.getFormByMarker('contact_form');

// Extrair IDs necessários
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Agora você pode enviar

Por que é necessário? O OneEntry precisa saber:

• Qual modelo de formulário usar
• Onde armazenar os dados
• Quais regras de validação aplicar

Estrutura dos Dados de Formulário

O array formData contém objetos de campo:

formData: [
  {
    marker: "field_name",     // Identificador do campo
    type: "text"              // Tipo do campo
    value: "user_input",      // Entrada do usuário
  }
]

Importante:

• marker deve corresponder aos marcadores de campo da definição do formulário
• type é útil para validação
• value contém a entrada do usuário

Status da Submissão

Use status para rastrear o estado da submissão:

Status	Significado	Quando Usar
"sent"	Submetido com sucesso	Padrão para novas submissões
"pending"	Aguardando revisão	Moderação necessária
"processed"	Tratado pelo admin	Marcado como revisado
"archived"	Submissão antiga/fechada	Manter para registros

Paginação

Recupere submissões em lotes.

Marcador do Formulário

Uma maneira de identificar submissões:

Identificador	O que é	Quando Usar
Marcador do Formulário	Identificador do modelo de formulário	Obter todas as submissões para um formulário específico

---

📊 Tabela de Referência Rápida

Método	Descrição	Caso de Uso
postFormsData()	Enviar novos dados de formulário	O usuário envia o formulário de contato
getFormsData()	Obter todas as submissões (paginação)	Painel do admin mostrando todos os formulários
getFormsDataByMarker()	Obter submissões para um formulário específico	Visualizar todas as submissões do formulário de contato

❓ Perguntas Frequentes (FAQ)

Como eu envio um formulário?

Você precisa de três coisas:

1. Configuração do formulário de Forms.getFormByMarker()
2. Dados de entrada do usuário
3. Chamar FormData.postFormsData()

---

Posso atualizar os dados do formulário enviado?

Não diretamente. As submissões de formulários são tipicamente imutáveis para manter a integridade dos dados.

Soluções alternativas:

• Enviar uma nova versão com dados atualizados
• Usar o campo status para marcar submissões antigas como obsoletas
• Implementar lógica de atualização personalizada em seu backend

---

Como eu lido com uploads de arquivos em formulários?

Faça upload de arquivos separadamente usando o módulo FileUploading, depois inclua as URLs dos arquivos nos dados do formulário:

---

Como eu filtro submissões por data?

Busque todas as submissões e filtre do lado do cliente

---

Posso pesquisar submissões por valor de campo?

Sim, busque submissões e pesquise do lado do cliente

---

Como eu pagino todas as submissões?

Use offset e limit

---

Qual é a diferença entre getFormsData() e getFormsDataByMarker()?

Método	O que Retorna	Quando Usar
getFormsData()	Todas as submissões de todos os formulários	Painel do admin mostrando tudo
getFormsDataByMarker()	Submissões de um formulário específico	Visualizar apenas submissões do formulário de contato

---

Como eu lido com erros de validação?

Use try/catch e verifique as mensagens de erro

---

💡 Notas Importantes

⚠️ Configuração do Formulário Necessária

Você não pode enviar formulários sem configuração:

• formModuleConfigId e moduleEntityIdentifier são obrigatórios
• Obtenha esses de Forms.getFormByMarker() antes de enviar
• Armazene-os em seu aplicativo para evitar chamadas de API repetidas

---

🔒 Considerações de Segurança

Nunca exponha dados sensíveis:

• Não envie senhas em texto simples
• Valide a entrada tanto no cliente quanto no servidor
• Limpe a entrada do usuário antes de exibir

---

📦 Conjuntos de Dados Grandes

A paginação é importante:

• Não busque milhares de submissões de uma vez
• Use limit e offset para paginação
• Considere o cache para dados acessados com frequência

---

🔄 Somente Leitura Após Submissão

Os dados do formulário são imutáveis:

• Não é possível atualizar submissões via SDK
• Envie uma nova versão se mudanças forem necessárias
• Use o campo status para rastrear o estado da submissão

---

🎓 Melhores Práticas

• Cache a configuração do formulário - Evite buscar a cada submissão
• Valide antes de enviar - Verifique campos obrigatórios do lado do cliente
• Use paginação - Busque submissões em lotes
• Lide com erros de forma elegante - Sempre use try/catch
• Use marcadores de forma consistente - Referencie formulários pelo marcador, não pelo ID
• Rastreie o status da submissão - Use o campo de status para organizar submissões
• Exporte dados regularmente - Faça backup das submissões para CSV/banco de dados
• Monitore novas submissões - Implemente polling ou webhooks

---

Definição do módulo FormData

const { FormData } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

Configurações do formulário:

1. Obtenha o formulário pelo marcador usando Forms.getFormByMarker('seu-marcador-de-formulário').
2. Use o campo moduleFormConfigs do formulário recuperado para a configuração usada ao enviar os dados do formulário.
3. Crie o corpo usando moduleFormConfig e poste os dados do formulário.

const formModuleConfigId = moduleFormConfigs[0].id;
const moduleEntityIdentifier = moduleFormConfigs[0].entityIdentifiers[0].id;
const body = {
  "formIdentifier": "seu-marcador-de-formulário",
  "formModuleConfigId": formModuleConfigId,
  "moduleEntityIdentifier": moduleEntityIdentifier,
  "replayTo": null,
  "status": "sent",
  "formData": [...]
};
const response = await FormData.postFormsData(body);

---

🔗 Documentação Relacionada

• Módulo de Formulários - Criar e gerenciar estruturas de formulários
• Módulo de FileUploading - Lidar com uploads de arquivos em formulários
• Módulo de Eventos - Configurar notificações baseadas em eventos
• Módulo de Usuários - Gerenciar usuários que enviam formulários

---