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:

O usuário preenche o formulário de contato
↓
postFormsData() → Salvo no OneEntry
↓
getFormsDataByMarker() → O OneEntry retorna os dados
↓
O Admin visualiza as submissões 

O que você pode fazer:

• 📤 Enviar formulários - Enviar dados preenchidos pelo usuário para o OneEntry
• 📥 Visualizar 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 → Responde 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
      },
    ]
  };

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 dos dados do formulário
   ↓
5. Notificações enviadas (e-mail, webhook)
   ↓
6. O Admin recupera com getFormsDataByMarker()
   ↓
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 de texto ú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 do 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 do 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
getFormsDataByMarker()	Obter submissões para formulário específico	Visualizar todas as submissões do formulário de contato

❓ Perguntas Frequentes (FAQ)

Como faço para enviar 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 frontend

---

Como faço para lidar com uploads de arquivos em formulários?

Basta usar File ou FileList com FormData.postFormsData() ou Carregar arquivos separadamente usando o módulo FileUploading, e depois incluir URLs de arquivos nos dados do formulário.

---

Como filtro submissões por data?

Use parâmetros do corpo dateFrom e dateTo.

---

Posso pesquisar submissões por valor de campo?

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

---

Como faço para paginar todas as submissões?

Use offset e limit.

---

Como 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 a 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 envio
• Valide antes de enviar - Verifique campos obrigatórios no 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 Upload de Arquivos - 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

---