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 o envio (nome, e-mail, mensagem)
3. Recuperar - Você busca os envios para visualizar, exportar ou analisar
4. Gerenciar - Filtrar, pesquisar e organizar as respostas do formulário

Fluxo de trabalho no mundo real:

User fills contact form
↓
postFormsData() → Saved in OneEntry
↓
getFormsDataByMarker() → OneEntry returns data
↓
Admin views submissions 

O que você pode fazer:

• 📤 Enviar formulários - Enviar dados preenchidos pelo usuário para o OneEntry
• 📥 Visualizar envios - Obter todas as respostas do formulário com paginação
• 🔍 Pesquisar envios - Encontrar envios específicos por marcador ou filtro
• 📊 Exportar dados - Recuperar envios 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 Envio de Formulário

Cada envio no OneEntry possui:

  const body: IBodyPostFormData = {
    formIdentifier: 'contact_form', // Form marker
    formModuleConfigId: 9,          // Module config ID
    moduleEntityIdentifier: 'blog', // Module entity identifier
    replayTo: null,                 // Email address to reply to
    status: 'sent',                 // Submission status
    formData: [                     // Form fields
      {
        marker: 'string',           // Field marker
        type: 'string',             // Field type
        value: 'Test',              // Field value
      },
    ]
  };

Ciclo de Vida dos Dados de Formulário

1. User fills form in browser
   ↓
2. Frontend validates input
   ↓
3. postFormsData() sends to OneEntry
   ↓
4. OneEntry validates & stores form data submission
   ↓
5. Notifications sent (email, webhook)
   ↓
6. Admin retrieves with getFormsDataByMarker()
   ↓
7. Review, export, or respond

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 clientes potenciais	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 e avaliações de clientes	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 de 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 isso:

// Fetch form
const form = await Forms.getFormByMarker('contact_form');

// Extract required IDs
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Now you can submit

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", // Field identifier
    type: "text"          // Field type
    value: "user_input",  // User's input
  }
]

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 do Envio

Use status para rastrear o estado do envio:

Status	Significado	Quando Usar
"sent"	Enviado com sucesso	Padrão para novos envios
"pending"	Aguardando revisão	Moderação necessária
"processed"	Tratado pelo administrador	Marcado como revisado
"archived"	Envio antigo/fechado	Manter para registros

Paginação

Recupere envios em lotes.

Marcador do Formulário

Uma maneira de identificar envios:

Identificador	O que é	Quando Usar
Marcador do Formulário	Identificador do modelo do formulário	Obter todos os envios 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 envios para formulário específico	Visualizar todos os envios 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. Os envios 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 envios antigos como obsoletos
• Implementar lógica de atualização personalizada em seu frontend

---

Como eu lido 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 eu filtro envios por data?

Use os parâmetros do corpo dateFrom e dateTo.

---

Posso pesquisar envios por valor de campo?

Sim, busque envios e pesquise do lado do cliente.

---

Como eu pagino todos os envios?

Use offset e limit.

---

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 dados 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 envios de uma vez
• Use limit e offset para paginação
• Considere o cache para dados acessados com frequência

---

🔄 Somente Leitura Após o Envio

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

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

---

🎓 Melhores Práticas

• Cache a configuração do formulário - Evite buscar a cada envio
• Valide antes de enviar - Verifique campos obrigatórios do lado do cliente
• Use paginação - Busque envios em lotes
• Lide com erros de forma elegante - Sempre use try/catch
• Use marcadores de forma consistente - Referencie formulários por marcador, não por ID
• Rastreie o status do envio - Use o campo de status para organizar envios
• Exporte dados regularmente - Faça backup de envios para CSV/banco de dados
• Monitore novos envios - 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

---