Introducción

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

🎯 ¿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 los 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.

---

📖 Explicación Simple

Imagina que tienes un formulario de contacto en tu sitio web. Cuando los usuarios lo llenan:

1. Enviar - El usuario hace clic en "Enviar" → Los datos del formulario van a OneEntry
2. Almacenar - OneEntry guarda el envío (nombre, correo electrónico, mensaje)
3. Recuperar - Tú obtienes los envíos para ver, exportar o analizar
4. Gestionar - Filtrar, buscar y organizar las respuestas del formulario

Flujo de trabajo en el mundo real:

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

Lo que puedes hacer:

• 📤 Enviar formularios - Enviar datos llenos por el usuario a OneEntry
• 📥 Ver envíos - Obtener todas las respuestas del formulario con paginación
• 🔍 Buscar envíos - Encontrar envíos específicos por marcador o filtro
• 📊 Exportar datos - Recuperar envíos para informes y análisis
• 📧 Gestionar respuestas - Rastrear envíos de formularios en un solo lugar

Escenarios de ejemplo:

Escenario	Qué Sucede
Formulario de Contacto	El usuario envía → Recibes notificación por correo → Ver en el panel de control
Encuesta	Recoger respuestas → Exportar a CSV → Analizar resultados
Registro	El usuario se registra → Datos almacenados → Enviar correo de confirmación
Comentarios	El cliente deja comentarios → El equipo revisa → Responder al cliente

---

✨ 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 formularios.

Estructura del Envío del Formulario

Cada envío en OneEntry tiene:

  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 de los Datos del Formulario

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 Comunes

Caso de Uso	Descripción	Ejemplo
Formularios de Contacto	Los clientes se comunican con preguntas	El equipo de soporte revisa y responde
Generación de Leads	Recoger información de clientes potenciales	El equipo de ventas hace seguimiento
Encuestas	Recoger comentarios y opiniones	El marketing analiza los resultados
Registros	Registrarse para eventos, boletines	Rastrear asistentes/suscriptores
Solicitudes de Empleo	Recoger currículos y cartas de presentación	Recursos humanos revisa candidatos
Formularios de Comentarios	Satisfacción del cliente y reseñas	Mejorar productos/servicios

---

📋 Lo Que Necesitas Saber

Enviar Formularios Requiere Configuración

Antes de enviar, necesitas:

1. Marcador del formulario - Identificador de texto único del formulario
2. ID de configuración del módulo del formulario - De la configuración del formulario
3. Identificador de entidad del módulo - De la configuración del formulario

Cómo obtener estos:

// 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 qué se necesita? OneEntry necesita saber:

• Qué plantilla de formulario usar
• Dónde almacenar los datos
• Qué reglas de validación aplicar

Estructura de los Datos del Formulario

El array formData contiene objetos de campo:

formData: [
  {
    marker: "field_name", // Field identifier
    type: "text"          // Field type
    value: "user_input",  // User's input
  }
]

Importante:

• marker debe coincidir con los marcadores de campo de la definición del formulario
• type útil para la validación
• value contiene la entrada del usuario

Estado del Envío

Usa status para rastrear el estado del envío:

Estado	Significado	Cuándo Usar
"sent"	Enviado con éxito	Predeterminado para nuevos envíos
"pending"	En espera de revisión	Moderación requerida
"processed"	Manejado por el administrador	Marcado como revisado
"archived"	Envío antiguo/cerrado	Mantener para registros

Paginación

Recupera envíos en lotes.

Marcador del Formulario

Una forma de identificar envíos:

Identificador	Qué Es	Cuándo Usar
Marcador del Formulario	Identificador de plantilla del formulario	Obtener todos los envíos para un formulario específico

---

📊 Tabla de Referencia Rápida

Método	Descripción	Caso de Uso
postFormsData()	Enviar nuevos datos del formulario	El usuario envía el formulario de contacto
getFormsDataByMarker()	Obtener envíos para un formulario específico	Ver todos los envíos del formulario de contacto

❓ Preguntas Frecuentes (FAQ)

¿Cómo envío un formulario?

Necesitas tres cosas:

1. Configuración del formulario de Forms.getFormByMarker()
2. Datos de entrada del usuario
3. Llamar a FormData.postFormsData()

---

¿Puedo actualizar los datos del formulario enviados?

No directamente. Los envíos de formularios son típicamente inmutables para mantener la integridad de los datos.

Soluciones alternativas:

• Enviar una nueva versión con datos actualizados
• Usar el campo status para marcar envíos antiguos como obsoletos
• Implementar lógica de actualización personalizada en tu frontend

---

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

Simplemente usa File o FileList con FormData.postFormsData() o sube archivos por separado usando el módulo FileUploading, luego incluye las URL de los archivos en los datos del formulario.

---

¿Cómo filtro envíos por fecha?

Usa los parámetros del cuerpo dateFrom y dateTo.

---

¿Puedo buscar envíos por valor de campo?

Sí, recupera envíos y busca del lado del cliente.

---

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

Usa offset y limit.

---

¿Cómo manejo errores de validación?

Usa try/catch y verifica los mensajes de error.

---

💡 Notas Importantes

⚠️ Se Requiere Configuración del Formulario

No puedes enviar formularios sin configuración:

• formModuleConfigId e moduleEntityIdentifier son requeridos
• Obtén estos de Forms.getFormByMarker() antes de enviar
• Almacénalos en tu aplicación para evitar llamadas API repetidas

---

🔒 Consideraciones de Seguridad

Nunca expongas datos sensibles:

• No envíes contraseñas en texto plano
• Valida la entrada tanto en el cliente como en el servidor
• Sanea la entrada del usuario antes de mostrarla

---

📦 Conjuntos de Datos Grandes

La paginación es importante:

• No recuperes miles de envíos a la vez
• Usa limit y offset para la paginación
• Considera el almacenamiento en caché para datos de acceso frecuente

---

🔄 Solo Lectura Después del Envío

Los datos del formulario son inmutables:

• No se pueden actualizar los envíos a través del SDK
• Envía una nueva versión si se necesitan cambios
• Usa el campo status para rastrear el estado del envío

---

🎓 Mejores Prácticas

• Caché de configuración del formulario - Evita recuperar en cada envío
• Valida antes de enviar - Verifica campos requeridos del lado del cliente
• Usa paginación - Recupera envíos en lotes
• Maneja errores de manera elegante - Siempre usa try/catch
• Usa marcadores de manera consistente - Referencia formularios por marcador, no por ID
• Rastrea el estado del envío - Usa el campo de estado para organizar envíos
• Exporta datos regularmente - Haz copias de seguridad de los envíos a CSV/base de datos
• Monitorea nuevos envíos - Implementa sondeo o webhooks

---

Definición del módulo FormData

const { FormData } = defineOneEntry(
  "tu-url-del-proyecto", {
    "token": "tu-token-de-aplicación"
  }
);

Configuración del formulario:

1. Obtén el formulario por marcador usando Forms.getFormByMarker('tu-marcador-de-formulario').
2. Usa el campo moduleFormConfigs del formulario recuperado para la configuración utilizada al enviar los datos del formulario.
3. Crea el cuerpo usando moduleFormConfig y publica los datos del formulario.

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

---

🔗 Documentación Relacionada

• Módulo de Formularios - Crea y gestiona estructuras de formularios
• Módulo de Carga de Archivos - Maneja cargas de archivos en formularios
• Módulo de Eventos - Configura notificaciones impulsadas por eventos
• Módulo de Usuarios - Gestiona usuarios que envían formularios

---