Pular para o conteúdo principal

Introdução

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

Mais informações sobre formulários no painel de administração do OneEntry: https://doc.oneentry.cloud/docs/category/forms

🎯 O que este módulo faz?​

O módulo FormData permite que você envie formulários preenchidos pelos usuários (formulários de contato, pesquisas, registros) para o OneEntry e recupere, atualize ou exclua 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.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { FormData } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Construa o corpo a partir da configuração do formulário e envie-o:

// 1. Fetch the form to read its module config.
const form = await Forms.getFormByMarker("contact_form");
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// 2. Submit the user's input.
const response = await FormData.postFormsData({
  formIdentifier: "contact_form",
  formModuleConfigId,
  moduleEntityIdentifier,
  replayTo: null,
  status: "sent",
  formData: [
    { marker: "name", type: "string", value: "Jack" },
  ],
});

console.log(response);

Para ler os envios posteriormente, chame getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

✨ 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 um formulário. Cada envio é construído a partir de um array formData de objetos de campo (marker, type, value) além dos identificadores de configuração do formulário.

Estrutura do corpo do envio​

postFormsData aceita um IBodyPostFormData:

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

📋 O que Você Precisa Saber​

O envio requer a configuração do formulário​

Antes de enviar, você precisa de três valores, todos lidos do próprio formulário:

  1. Marcador do formulário (formIdentifier) — o identificador de texto do formulário
  2. formModuleConfigId — da moduleFormConfigs do formulário
  3. moduleEntityIdentifier — da moduleFormConfigs do formulário
const form = await Forms.getFormByMarker('contact_form');
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

Armazene esses valores em cache para não precisar buscar o formulário em cada envio.

Campos do formData​

Cada entrada no array formData descreve um campo:

  • marker — deve corresponder a um marcador de campo da definição do formulário
  • type — o tipo do campo (usado para validação e manipulação de arquivos)
  • value — a entrada do usuário

Campos do tipo file / image / groupOfImages são enviados automaticamente através do módulo FileUploading quando você passa um File/FileList/Blob como o value.

Status do envio​

Use o campo status para rastrear o estado do envio. "sent" é o valor típico para novos envios; você pode posteriormente mover um envio para um estado revisado/arquivado com updateFormsDataStatusByid().

Atualizando e excluindo envios​

Os envios não são imutáveis. Usuários autenticados podem alterá-los ou removê-los:

  • updateFormsDataByid(id, body) — edite um envio armazenado pelo id 🔐
  • updateFormsDataStatusByid(id, body) — altere apenas o status de um envio pelo id 🔐
  • deleteFormsDataByid(id) — exclua um envio pelo id 🔐

Lendo envios​

getFormsDataByMarker retorna envios para um formulário. Navegue pelos resultados com offset / limit, e refine com o body da solicitação (por exemplo, status, dateFrom, dateTo, userIdentifier).

Buscando envios por significado​

getFormsDataByVectorSearch(body, langCode, offset, limit) realiza uma busca semântica (vetorial) sobre os envios: você passa um queryText em linguagem natural e recebe de volta os registros que correspondem a ele em significado, não por palavra-chave literal.

Seus registros usam um tipo diferente do restante do módulo - IFormDataSearchEntity em vez de IFormDataEntity. Ambos carregam id, formIdentifier, time e formData, mas a entidade de busca expõe adicionalmente os campos de moderação e remetente do registro bruto:

CampoTipoSignificado
status'sent' | 'banned' | 'deleted' | 'moderation' | 'approved'Status de moderação do registro
ipstringEndereço IP de onde o formulário foi enviado
fingerprintstringImpressão digital do dispositivo do remetente
isUserAdminbooleanSe um administrador enviou o registro
userIdentifierstringQuem enviou o formulário
entityIdentifierstringA entidade à qual o registro pertence
parentIdnumberRegistro de dados do formulário pai

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
postFormsData()Enviar novos dados de formulárioUsuário envia formulário de contato
getFormsDataByMarker()Obter envios para formulário específicoVisualizar todos os envios do formulário de contato
updateFormsDataByid() 🔐Atualizar um envio de formulário pelo idEditar um envio armazenado
updateFormsDataStatusByid() 🔐Atualizar o status de um envio pelo idMarcar como processado/arquivado
deleteFormsDataByid() 🔐Excluir um envio de formulário pelo idRemover um envio
getFormsDataByVectorSearch()Busca semântica (vetorial) para dados de formulárioEncontrar envios por significado, não por palavras-chave

🔐 métodos requerem autorização do usuário — veja AuthProvider. postFormsData() e getFormsDataByMarker() são públicos.

❓ Perguntas Frequentes (FAQ)​

Como eu envio um formulário?​

Busque o formulário com Forms.getFormByMarker(), leia formModuleConfigId e moduleEntityIdentifier de suas moduleFormConfigs, construa o corpo e, em seguida, chame FormData.postFormsData(body). Veja a seção de Início Rápido acima.

Posso atualizar ou excluir dados de formulário enviados?​

Sim. Os envios podem ser alterados ou removidos via SDK (isso requer autorização do usuário):

  • updateFormsDataByid() — edite um envio armazenado pelo id
  • updateFormsDataStatusByid() — altere apenas o status de um envio pelo id
  • deleteFormsDataByid() — exclua um envio pelo id

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

Passe um File / FileList / Blob como o value de um campo e postFormsData() o enviará para você, ou faça o upload separadamente com o módulo FileUploading e inclua as URLs retornadas em formData.

Como eu filtro envios por data?​

Passe dateFrom e dateTo no body da solicitação de getFormsDataByMarker().

Como eu pagino por todos os envios?​

Use os argumentos offset e limit de getFormsDataByMarker().

🎓 Melhores Práticas​

  • Armazene em cache a configuração do formulário (formModuleConfigId, moduleEntityIdentifier) para evitar buscar o formulário em cada envio.
  • Valide campos obrigatórios no lado do cliente antes de enviar; o OneEntry também valida no lado do servidor.
  • Paginar leituras com offset / limit em vez de buscar tudo de uma vez.
  • Referencie formulários por marcador, não por ID numérico.
  • Use o campo status (e updateFormsDataStatusByid) para organizar envios.
  • Trate erros com try/catch e verifique a forma de retorno IError.

🔗 Documentação Relacionada​