Saltar al contenido principal

Introducción

Maneja envíos de formularios y recupera datos de formularios.

Más información sobre formularios en el panel de administración de OneEntry: https://doc.oneentry.cloud/docs/category/forms

🎯 ¿Qué hace este módulo?​

El módulo FormData te permite enviar formularios llenos por los usuarios (formularios de contacto, encuestas, registros) a OneEntry y recuperar, actualizar o eliminar datos enviados para análisis, informes y gestión.

Piénsalo como tu gestor de envíos de formularios: los usuarios envían formularios, tú los almacenas en OneEntry y los recuperas siempre que necesites ver respuestas, generar informes o analizar datos.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

Construye el cuerpo a partir de la configuración del formulario y envíalo:

// 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 leer envíos más tarde, llama a getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

✨ Conceptos Clave​

¿Qué es el Datos del Formulario?​

Los datos del formulario son la información que los usuarios envían a través de un formulario. Cada envío se construye a partir de un array formData de objetos de campo (marker, type, value) más los identificadores de configuración del formulario.

Estructura del cuerpo de envío​

postFormsData acepta un 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' },
  ],
};

📋 Lo Que Necesitas Saber​

El envío requiere la configuración del formulario​

Antes de enviar, necesitas tres valores, todos leídos del propio formulario:

  1. Marcador del formulario (formIdentifier) — el identificador de texto del formulario
  2. formModuleConfigId — de los moduleFormConfigs del formulario
  3. moduleEntityIdentifier — de los moduleFormConfigs del formulario
const form = await Forms.getFormByMarker('contact_form');
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

Almacena estos valores en caché para que no vuelvas a obtener el formulario en cada envío.

Campos de formData​

Cada entrada en el array formData describe un campo:

  • marker — debe coincidir con un marcador de campo de la definición del formulario
  • type — el tipo de campo (utilizado para validación y manejo de archivos)
  • value — la entrada del usuario

Los campos de tipo file / image / groupOfImages se suben automáticamente a través del módulo FileUploading cuando pasas un File/FileList/Blob como value.

Estado del envío​

Utiliza el campo status para rastrear el estado del envío. "sent" es el valor típico para nuevos envíos; más tarde puedes mover un envío a un estado revisado/archivado con updateFormsDataStatusByid().

Actualización y eliminación de envíos​

Los envíos no son inmutables. Los usuarios autenticados pueden cambiarlos o eliminarlos:

  • updateFormsDataByid(id, body) — edita un envío almacenado por id 🔐
  • updateFormsDataStatusByid(id, body) — cambia solo el estado de un envío por id 🔐
  • deleteFormsDataByid(id) — elimina un envío por id 🔐

Lectura de envíos​

getFormsDataByMarker devuelve envíos para un formulario. Páginalos con offset / limit, y estrecha con el body de la solicitud (por ejemplo, status, dateFrom, dateTo, userIdentifier).

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
postFormsData()Enviar nuevos datos de formularioEl usuario envía un formulario de contacto
getFormsDataByMarker()Obtener envíos para un formulario específicoVer todos los envíos del formulario de contacto
updateFormsDataByid() 🔐Actualizar un envío de formulario por idEditar un envío almacenado
updateFormsDataStatusByid() 🔐Actualizar el estado de un envío por idMarcar como procesado/archivado
deleteFormsDataByid() 🔐Eliminar un envío de formulario por idEliminar un envío

🔐 los métodos requieren autorización del usuario — consulta AuthProvider. postFormsData() y getFormsDataByMarker() son públicos.

❓ Preguntas Frecuentes (FAQ)​

¿Cómo envío un formulario?​

Obtén el formulario con Forms.getFormByMarker(), lee formModuleConfigId y moduleEntityIdentifier de sus moduleFormConfigs, construye el cuerpo y luego llama a FormData.postFormsData(body). Consulta la sección de Inicio Rápido arriba.

¿Puedo actualizar o eliminar datos de formulario enviados?​

Sí. Los envíos pueden ser cambiados o eliminados a través del SDK (esto requiere autorización del usuario):

  • updateFormsDataByid() — edita un envío almacenado por id
  • updateFormsDataStatusByid() — cambia solo el estado de un envío por id
  • deleteFormsDataByid() — elimina un envío por id

¿Cómo manejo las cargas de archivos en formularios?​

Pasa un File / FileList / Blob como value de un campo y postFormsData() lo sube por ti, o súbelo por separado con el módulo FileUploading e incluye las URLs devueltas en formData.

¿Cómo filtro envíos por fecha?​

Pasa dateFrom y dateTo en el body de la solicitud de getFormsDataByMarker().

¿Cómo pagino a través de todos los envíos?​

Utiliza los argumentos offset y limit de getFormsDataByMarker().

🎓 Mejores Prácticas​

  • Almacena en caché la configuración del formulario (formModuleConfigId, moduleEntityIdentifier) para evitar volver a obtener el formulario en cada envío.
  • Valida los campos requeridos del lado del cliente antes de enviar; OneEntry también valida del lado del servidor.
  • Pagina las lecturas con offset / limit en lugar de obtener todo de una vez.
  • Referencia formularios por marcador, no por ID numérico.
  • Utiliza el campo status (y updateFormsDataStatusByid) para organizar los envíos.
  • Maneja errores con try/catch y verifica la forma de retorno de IError.

🔗 Documentación Relacionada​